diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/modular')
-rw-r--r-- | Master/texmf-dist/doc/latex/modular/README-doc.md | 8 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/modular/README.md | 45 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/modular/article.tex | 15 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/modular/article_fail.tex | 12 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/modular/content.tex | 3 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/modular/coseoul_limitations.tex | 20 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/modular/doc/content.tex | 5 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/modular/doc/example/octopus/article.tex | 10 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/modular/habitat.tex | 3 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/modular/introduction.tex | 9 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/modular/lifecycle.tex | 4 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/modular/modular.pdf | bin | 0 -> 141568 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/latex/modular/modular.tex | 24 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/modular/modular_to_the_rescue.tex | 14 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/modular/prerequisites.tex | 20 |
15 files changed, 192 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/modular/README-doc.md b/Master/texmf-dist/doc/latex/modular/README-doc.md new file mode 100644 index 00000000000..33aa60fc1e4 --- /dev/null +++ b/Master/texmf-dist/doc/latex/modular/README-doc.md @@ -0,0 +1,8 @@ +The main documentation file is `modular.tex`. +Build it to produce the package documentaiton. + +The documentation refers to an example project whose sources are in `example/`. +Build `example/octopus/article.tex` to see a short article about octopuses. +Build `example/article_failed.tex` for a failed attempt at re-using the octopus article's content in an article about sea animals. +Build `example/article.tex` for a successful attempt using `modular`. + diff --git a/Master/texmf-dist/doc/latex/modular/README.md b/Master/texmf-dist/doc/latex/modular/README.md new file mode 100644 index 00000000000..cf1f01d46e9 --- /dev/null +++ b/Master/texmf-dist/doc/latex/modular/README.md @@ -0,0 +1,45 @@ +``` +Copyright 2017 Daniel Thomas Sank (sank.daniel@gmail.com) + +This work may be distributed and/or modified under the conditions of the LaTeX +Project Public License, either version 1.3 of this license or (at your option) +any later version. The latest version of this license is in +http://www.latex-project.org/lppl.txt +and version 1.3 or later is part of all distributions of LaTeX version +2005/12/01 or later. + +This work has the LPPL maintenance status `maintained'. + +The Current Maintainer of this work is Daniel Thomas Sank. + +This work consists of the files modular.sty and README.md. +``` +# modular + +## Abstract + +The `\chapter`, `\section`, etc. commands in LaTeX are great until you want to reuse document fragments in multiple containing documents where the heading levels need to be different. +For example, suppose you write an article about octopuses containing `\section`'s "Habitat" and "Life cycle". +Now suppose you want to write an article about sea animals with a `\section` for octopuses. +Within that section, the parts about habitat and life cycle should be *sub*sections. +The built-in LaTeX commands do not support this, but `modular` does! + +We need to make our headings relative rather than absolute, and we need a way to import document fragments at levels relative to the point from which they're imported. +The [`coseoul`](https://www.ctan.org/pkg/coseoul?lang=en) package gives us relative headings, but it doesn't provide the import mechanism we need. +This package builds on `coseoul` providing the `\subimportlevel` macro, which enables fully modular importing of sub-documents and gets the relative headings right. + +## Documentation + +See `doc/modular.pdf` distributed with this package. +It's source is `modular.tex`. +The source for the examples shown there are in the `documentation/example` and `documentation/example/octopus` directories. +You can build the files there yourself to experiment with the package. +See `documentation/README.md` for more information. + +## References + +See the package documentation for a more complete description of the problem this package solves and how to use the `subimportlevel` macro. +For an extended discussion of the modularity problem, a detailed review of failed attempts using only the `import` and `coseoul` packages, and a step-by-step explanation of how the `\subimportlevel` macro provided by this package works, see [this post](https://danielsank.github.io/tex_modularity/). + +This package is developed on [github](https://github.com/DanielSank/tex-modular). + diff --git a/Master/texmf-dist/doc/latex/modular/article.tex b/Master/texmf-dist/doc/latex/modular/article.tex new file mode 100644 index 00000000000..2d4b84bd811 --- /dev/null +++ b/Master/texmf-dist/doc/latex/modular/article.tex @@ -0,0 +1,15 @@ +\documentclass{article} +% modular must be installed for +% this example to build. If it's +% not in your LaTeX distribution, +% install the .sty file manually. +\usepackage{modular} +\title{Sea Animals} +\begin{document} +\maketitle +This is an article about sea animals. +The first section is about octopusus. +\levelstay{Octopuses} +\subimportlevel{./octopus/}{content.tex}{1} +\end{document} + diff --git a/Master/texmf-dist/doc/latex/modular/article_fail.tex b/Master/texmf-dist/doc/latex/modular/article_fail.tex new file mode 100644 index 00000000000..4f046ab6e80 --- /dev/null +++ b/Master/texmf-dist/doc/latex/modular/article_fail.tex @@ -0,0 +1,12 @@ +\documentclass{article} +\usepackage{coseoul} +\usepackage{import} +\title{Sea Animals} +\begin{document} +\maketitle +This is an article about sea animals. +The first section is about octopusus. +\levelstay{Octopuses} +\subimport*{./octopus/}{content.tex} +\end{document} + diff --git a/Master/texmf-dist/doc/latex/modular/content.tex b/Master/texmf-dist/doc/latex/modular/content.tex new file mode 100644 index 00000000000..25b51a3acae --- /dev/null +++ b/Master/texmf-dist/doc/latex/modular/content.tex @@ -0,0 +1,3 @@ +\subimport*{./}{habitat.tex} +\subimport*{./}{lifecycle.tex} + diff --git a/Master/texmf-dist/doc/latex/modular/coseoul_limitations.tex b/Master/texmf-dist/doc/latex/modular/coseoul_limitations.tex new file mode 100644 index 00000000000..f77344d0908 --- /dev/null +++ b/Master/texmf-dist/doc/latex/modular/coseoul_limitations.tex @@ -0,0 +1,20 @@ +\levelstay{\fixedwidth{coseoul} limitations} + +All listings here are taken directly from files included with this package so that you can access those files and build them yourself to see the examples in action. +All paths are relative to \fixedwidth{documentation/example}. + +Suppose we write an octopus article with two sections:\footnote{build \fixedwidth{octopus/article.tex} to see the article yourself.} + +\lstinputlisting[title=\textbf{octopus/article.tex}]{example/octopus/article.tex} + +\lstinputlisting[title=\textbf{octopus/content.tex}]{example/octopus/content.tex} + +\lstinputlisting[title=\textbf{octopus/habitat.tex}]{example/octopus/habitat.tex} + +\lstinputlisting[title=\textbf{octopus/lifecycle.tex}]{example/octopus/lifecycle.tex} +This works great. +Now let's try to use the octopus article as a sub-part of an article on sea animals: + +\lstinputlisting[title=\textbf{article\_fail.tex}]{example/article_fail.tex} +As you can see by building \fixedwidth{article\_fail.tex} yourself, the habitat and lifecycle parts come in as sections instead of subsections. + diff --git a/Master/texmf-dist/doc/latex/modular/doc/content.tex b/Master/texmf-dist/doc/latex/modular/doc/content.tex new file mode 100644 index 00000000000..3beaedc200c --- /dev/null +++ b/Master/texmf-dist/doc/latex/modular/doc/content.tex @@ -0,0 +1,5 @@ +\subimportlevel{./}{introduction.tex}{0} +\subimportlevel{./}{prerequisites.tex}{0} +\subimportlevel{./}{coseoul_limitations.tex}{0} +\subimportlevel{./}{modular_to_the_rescue.tex}{0} + diff --git a/Master/texmf-dist/doc/latex/modular/doc/example/octopus/article.tex b/Master/texmf-dist/doc/latex/modular/doc/example/octopus/article.tex new file mode 100644 index 00000000000..ff8f43f049e --- /dev/null +++ b/Master/texmf-dist/doc/latex/modular/doc/example/octopus/article.tex @@ -0,0 +1,10 @@ +\documentclass{article} +\usepackage{coseoul} +\usepackage{import} +\title{Octopuses} +\begin{document} +\maketitle +This is an article about octopuses. +\subimport*{./}{content.tex} +\end{document} + diff --git a/Master/texmf-dist/doc/latex/modular/habitat.tex b/Master/texmf-dist/doc/latex/modular/habitat.tex new file mode 100644 index 00000000000..fa3b22a9403 --- /dev/null +++ b/Master/texmf-dist/doc/latex/modular/habitat.tex @@ -0,0 +1,3 @@ +\levelstay{Habitat} +Octopuses live in the ocean. + diff --git a/Master/texmf-dist/doc/latex/modular/introduction.tex b/Master/texmf-dist/doc/latex/modular/introduction.tex new file mode 100644 index 00000000000..1978b7ede13 --- /dev/null +++ b/Master/texmf-dist/doc/latex/modular/introduction.tex @@ -0,0 +1,9 @@ +\levelstay{What problem does this solve?} +Suppose you write an article about octopuses. +This article might have a sections ``Life cycle'' and ``Habitat''. +Now suppose you want to write an article on sea animals and you want to have a section on octopuses. +Obviously, we would like to import the octopus article we already wrote as a section of the sea animals article, but this is nontrivial because we need to somehow convert the habitat and lifecycle sections into subsections only when importing the octopus sub-document into the sea animal article! +This package provides the \fixedwidth{subimportlevel} macro to make that possible. + +For a very detailed discussion on the issue of modularity and how this package solves it, see \href{https://danielsank.github.io/tex_modularity/}{https://danielsank.github.io/tex\_modularity}. + diff --git a/Master/texmf-dist/doc/latex/modular/lifecycle.tex b/Master/texmf-dist/doc/latex/modular/lifecycle.tex new file mode 100644 index 00000000000..b2e4d335c98 --- /dev/null +++ b/Master/texmf-dist/doc/latex/modular/lifecycle.tex @@ -0,0 +1,4 @@ +\levelstay{Life cycle} +Octopuses start out as plankton, but can grow to +hundreds of pounds. + diff --git a/Master/texmf-dist/doc/latex/modular/modular.pdf b/Master/texmf-dist/doc/latex/modular/modular.pdf Binary files differnew file mode 100644 index 00000000000..1ea2ef63f33 --- /dev/null +++ b/Master/texmf-dist/doc/latex/modular/modular.pdf diff --git a/Master/texmf-dist/doc/latex/modular/modular.tex b/Master/texmf-dist/doc/latex/modular/modular.tex new file mode 100644 index 00000000000..452aaf4bebd --- /dev/null +++ b/Master/texmf-dist/doc/latex/modular/modular.tex @@ -0,0 +1,24 @@ +\documentclass{article} +\usepackage{modular} +\usepackage[pdfpagemode=UseNone,pdfstartview=FitH,colorlinks=true,linkcolor=blue,citecolor=blue,urlcolor=blue]{hyperref} +\usepackage{listings} +\lstset{language=[LaTeX]TeX, linewidth=0.9\textwidth, frame=single} + +\newcommand{\coseoul}{\texttt{coseoul}} +\newcommand{\fixedwidth}[1]{\texttt{#1}} +\newcommand{\levelstaytext}{\texttt{\backslash levelstay}} + +\title{Modular LaTeX Documents: \textbf{modular}} +\author{Daniel Thomas Sank} +\date{2016 December 27} + +\begin{document} + +\maketitle +\tableofcontents + +% \subimport* comes from the `import` package. +\subimport*{./}{content.tex} + +\end{document} + diff --git a/Master/texmf-dist/doc/latex/modular/modular_to_the_rescue.tex b/Master/texmf-dist/doc/latex/modular/modular_to_the_rescue.tex new file mode 100644 index 00000000000..7aa864e58a5 --- /dev/null +++ b/Master/texmf-dist/doc/latex/modular/modular_to_the_rescue.tex @@ -0,0 +1,14 @@ +\levelstay{\fixedwidth{modular} to the rescue} + +The \fixedwidth{modular} package provides the \fixedwidth{subimportlevel} macro to solve our problem: + +\lstinputlisting[title=\textbf{article.tex}]{example/article.tex} +When you build \fixedwidth{article.tex} you'll see that the habitat and lifecycle bits are subsections under the octopus section, just as we wanted! + +The \fixedwidth{subimportlevel} macro takes three arguments: +\begin{itemize} + \item The relative path of the directory containing the file to import. + \item The file to import + \item The number of levels to go down when importing. Usually, this will be 0 or 1. +\end{itemize} + diff --git a/Master/texmf-dist/doc/latex/modular/prerequisites.tex b/Master/texmf-dist/doc/latex/modular/prerequisites.tex new file mode 100644 index 00000000000..dacebeca3c9 --- /dev/null +++ b/Master/texmf-dist/doc/latex/modular/prerequisites.tex @@ -0,0 +1,20 @@ +\levelstay{Prerequisite: \fixedwidth{coseoul}} +This package builds on the \fixedwidth{coseoul} package and works in concert with the macros defined in \fixedwidth{coseoul}. +We recommend reading the \fixedwidth{coseoul} documentation to at least get an idea of how it works before reading further here, but we also give a brief review. + +Commands like \fixedwidth{section} are absolute, i.e. the level depth is determined entirely by the command itself. +The \fixedwidth{coseoul} package introduces \fixedwidth{levelstay}, \fixedwidth{leveldown}, \fixedwidth{levelup}, and \fixedwidth{levelmultiup} commands. +These do exactly what they sound like, e.g. \fixedwidth{levelstay} makes a new heading at the same level you're at when you call the command. +Here's a simple example: +\begin{lstlisting} +\documentclass{article} +\begin{document} +\usepackage{coseoul} +\levelstay{This is a section} +\leveldown{This is a subsection} +\leveldown{This is a subsubsection} +\levelmultiup{2}{This is another section} +\end{document} +\end{lstlisting} +See the \fixedwidth{coseoul} documentation for details, but that's all there really is to \fixedwidth{coseoul}. + |