From e0c6872cf40896c7be36b11dcc744620f10adf1d Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 2 Sep 2019 13:46:59 +0900 Subject: Initial commit --- macros/latex/contrib/modular/README.md | 45 +++++++++++++++++++++ macros/latex/contrib/modular/doc/README-doc.md | 8 ++++ macros/latex/contrib/modular/doc/content.tex | 5 +++ .../contrib/modular/doc/coseoul_limitations.tex | 20 +++++++++ .../latex/contrib/modular/doc/example/article.tex | 15 +++++++ .../contrib/modular/doc/example/article_fail.tex | 12 ++++++ .../modular/doc/example/octopus/article.tex | 10 +++++ .../modular/doc/example/octopus/content.tex | 3 ++ .../modular/doc/example/octopus/habitat.tex | 3 ++ .../modular/doc/example/octopus/lifecycle.tex | 4 ++ macros/latex/contrib/modular/doc/introduction.tex | 9 +++++ macros/latex/contrib/modular/doc/modular.pdf | Bin 0 -> 141568 bytes macros/latex/contrib/modular/doc/modular.tex | 24 +++++++++++ .../contrib/modular/doc/modular_to_the_rescue.tex | 14 +++++++ macros/latex/contrib/modular/doc/prerequisites.tex | 20 +++++++++ macros/latex/contrib/modular/modular.sty | 24 +++++++++++ 16 files changed, 216 insertions(+) create mode 100644 macros/latex/contrib/modular/README.md create mode 100644 macros/latex/contrib/modular/doc/README-doc.md create mode 100644 macros/latex/contrib/modular/doc/content.tex create mode 100644 macros/latex/contrib/modular/doc/coseoul_limitations.tex create mode 100644 macros/latex/contrib/modular/doc/example/article.tex create mode 100644 macros/latex/contrib/modular/doc/example/article_fail.tex create mode 100644 macros/latex/contrib/modular/doc/example/octopus/article.tex create mode 100644 macros/latex/contrib/modular/doc/example/octopus/content.tex create mode 100644 macros/latex/contrib/modular/doc/example/octopus/habitat.tex create mode 100644 macros/latex/contrib/modular/doc/example/octopus/lifecycle.tex create mode 100644 macros/latex/contrib/modular/doc/introduction.tex create mode 100644 macros/latex/contrib/modular/doc/modular.pdf create mode 100644 macros/latex/contrib/modular/doc/modular.tex create mode 100644 macros/latex/contrib/modular/doc/modular_to_the_rescue.tex create mode 100644 macros/latex/contrib/modular/doc/prerequisites.tex create mode 100644 macros/latex/contrib/modular/modular.sty (limited to 'macros/latex/contrib/modular') diff --git a/macros/latex/contrib/modular/README.md b/macros/latex/contrib/modular/README.md new file mode 100644 index 0000000000..cf1f01d46e --- /dev/null +++ b/macros/latex/contrib/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/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 new file mode 100644 index 0000000000..1ea2ef63f3 Binary files /dev/null and b/macros/latex/contrib/modular/doc/modular.pdf differ 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}. + diff --git a/macros/latex/contrib/modular/modular.sty b/macros/latex/contrib/modular/modular.sty new file mode 100644 index 0000000000..72d6fc912a --- /dev/null +++ b/macros/latex/contrib/modular/modular.sty @@ -0,0 +1,24 @@ +% Copyright 2017 Daniel Thomas Sank (sank.daniel@gmail.com) +% +% This work may be distributed under the terms of the LPPL. +% See README.md for details. + +\NeedsTeXFormat{LaTeX2e} +\ProvidesPackage{modular}[2016/12/27 Modular document design] +\RequirePackage{ifthen} +\RequirePackage{coseoul} +\RequirePackage{import} + +\makeatletter +\newcounter{currentimportdepth} +\setcounter{currentimportdepth}{0} +\newcommand{\subimportlevel}[3]{ + \expandafter\edef\csname @currentlevel\thecurrentimportdepth\endcsname{\thecurrentlevel} + \addtocounter{currentimportdepth}{1} + \addtocounter{currentlevel}{-#3} + \subimport*{#1}{#2} + \addtocounter{currentimportdepth}{-1} + \setcounter{currentlevel}{\csname @currentlevel\thecurrentimportdepth\endcsname} + } +\makeatother + -- cgit v1.2.3