diff options
Diffstat (limited to 'macros/latex/contrib/modular/doc')
-rw-r--r-- | macros/latex/contrib/modular/doc/README-doc.md | 8 | ||||
-rw-r--r-- | macros/latex/contrib/modular/doc/content.tex | 5 | ||||
-rw-r--r-- | macros/latex/contrib/modular/doc/coseoul_limitations.tex | 20 | ||||
-rw-r--r-- | macros/latex/contrib/modular/doc/example/article.tex | 15 | ||||
-rw-r--r-- | macros/latex/contrib/modular/doc/example/article_fail.tex | 12 | ||||
-rw-r--r-- | macros/latex/contrib/modular/doc/example/octopus/article.tex | 10 | ||||
-rw-r--r-- | macros/latex/contrib/modular/doc/example/octopus/content.tex | 3 | ||||
-rw-r--r-- | macros/latex/contrib/modular/doc/example/octopus/habitat.tex | 3 | ||||
-rw-r--r-- | macros/latex/contrib/modular/doc/example/octopus/lifecycle.tex | 4 | ||||
-rw-r--r-- | macros/latex/contrib/modular/doc/introduction.tex | 9 | ||||
-rw-r--r-- | macros/latex/contrib/modular/doc/modular.pdf | bin | 0 -> 141568 bytes | |||
-rw-r--r-- | macros/latex/contrib/modular/doc/modular.tex | 24 | ||||
-rw-r--r-- | macros/latex/contrib/modular/doc/modular_to_the_rescue.tex | 14 | ||||
-rw-r--r-- | macros/latex/contrib/modular/doc/prerequisites.tex | 20 |
14 files changed, 147 insertions, 0 deletions
diff --git a/macros/latex/contrib/modular/doc/README-doc.md b/macros/latex/contrib/modular/doc/README-doc.md new file mode 100644 index 0000000000..33aa60fc1e --- /dev/null +++ b/macros/latex/contrib/modular/doc/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/macros/latex/contrib/modular/doc/content.tex b/macros/latex/contrib/modular/doc/content.tex new file mode 100644 index 0000000000..3beaedc200 --- /dev/null +++ b/macros/latex/contrib/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/macros/latex/contrib/modular/doc/coseoul_limitations.tex b/macros/latex/contrib/modular/doc/coseoul_limitations.tex new file mode 100644 index 0000000000..f77344d090 --- /dev/null +++ b/macros/latex/contrib/modular/doc/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/macros/latex/contrib/modular/doc/example/article.tex b/macros/latex/contrib/modular/doc/example/article.tex new file mode 100644 index 0000000000..2d4b84bd81 --- /dev/null +++ b/macros/latex/contrib/modular/doc/example/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/macros/latex/contrib/modular/doc/example/article_fail.tex b/macros/latex/contrib/modular/doc/example/article_fail.tex new file mode 100644 index 0000000000..4f046ab6e8 --- /dev/null +++ b/macros/latex/contrib/modular/doc/example/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/macros/latex/contrib/modular/doc/example/octopus/article.tex b/macros/latex/contrib/modular/doc/example/octopus/article.tex new file mode 100644 index 0000000000..ff8f43f049 --- /dev/null +++ b/macros/latex/contrib/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/macros/latex/contrib/modular/doc/example/octopus/content.tex b/macros/latex/contrib/modular/doc/example/octopus/content.tex new file mode 100644 index 0000000000..25b51a3aca --- /dev/null +++ b/macros/latex/contrib/modular/doc/example/octopus/content.tex @@ -0,0 +1,3 @@ +\subimport*{./}{habitat.tex} +\subimport*{./}{lifecycle.tex} + diff --git a/macros/latex/contrib/modular/doc/example/octopus/habitat.tex b/macros/latex/contrib/modular/doc/example/octopus/habitat.tex new file mode 100644 index 0000000000..fa3b22a940 --- /dev/null +++ b/macros/latex/contrib/modular/doc/example/octopus/habitat.tex @@ -0,0 +1,3 @@ +\levelstay{Habitat} +Octopuses live in the ocean. + diff --git a/macros/latex/contrib/modular/doc/example/octopus/lifecycle.tex b/macros/latex/contrib/modular/doc/example/octopus/lifecycle.tex new file mode 100644 index 0000000000..b2e4d335c9 --- /dev/null +++ b/macros/latex/contrib/modular/doc/example/octopus/lifecycle.tex @@ -0,0 +1,4 @@ +\levelstay{Life cycle} +Octopuses start out as plankton, but can grow to +hundreds of pounds. + diff --git a/macros/latex/contrib/modular/doc/introduction.tex b/macros/latex/contrib/modular/doc/introduction.tex new file mode 100644 index 0000000000..1978b7ede1 --- /dev/null +++ b/macros/latex/contrib/modular/doc/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/macros/latex/contrib/modular/doc/modular.pdf b/macros/latex/contrib/modular/doc/modular.pdf Binary files differnew file mode 100644 index 0000000000..1ea2ef63f3 --- /dev/null +++ b/macros/latex/contrib/modular/doc/modular.pdf diff --git a/macros/latex/contrib/modular/doc/modular.tex b/macros/latex/contrib/modular/doc/modular.tex new file mode 100644 index 0000000000..452aaf4beb --- /dev/null +++ b/macros/latex/contrib/modular/doc/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/macros/latex/contrib/modular/doc/modular_to_the_rescue.tex b/macros/latex/contrib/modular/doc/modular_to_the_rescue.tex new file mode 100644 index 0000000000..7aa864e58a --- /dev/null +++ b/macros/latex/contrib/modular/doc/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/macros/latex/contrib/modular/doc/prerequisites.tex b/macros/latex/contrib/modular/doc/prerequisites.tex new file mode 100644 index 0000000000..dacebeca3c --- /dev/null +++ b/macros/latex/contrib/modular/doc/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}. + |