texlive[44142] Master: modular (1may17)
commits+karl at tug.org
commits+karl at tug.org
Mon May 1 23:56:15 CEST 2017
Revision: 44142
http://tug.org/svn/texlive?view=revision&revision=44142
Author: karl
Date: 2017-05-01 23:56:14 +0200 (Mon, 01 May 2017)
Log Message:
-----------
modular (1may17)
Modified Paths:
--------------
trunk/Master/tlpkg/bin/tlpkg-ctan-check
trunk/Master/tlpkg/libexec/ctan2tds
trunk/Master/tlpkg/tlpsrc/collection-latexextra.tlpsrc
Added Paths:
-----------
trunk/Master/texmf-dist/doc/latex/modular/
trunk/Master/texmf-dist/doc/latex/modular/README-doc.md
trunk/Master/texmf-dist/doc/latex/modular/README.md
trunk/Master/texmf-dist/doc/latex/modular/article.tex
trunk/Master/texmf-dist/doc/latex/modular/article_fail.tex
trunk/Master/texmf-dist/doc/latex/modular/content.tex
trunk/Master/texmf-dist/doc/latex/modular/coseoul_limitations.tex
trunk/Master/texmf-dist/doc/latex/modular/doc/
trunk/Master/texmf-dist/doc/latex/modular/doc/content.tex
trunk/Master/texmf-dist/doc/latex/modular/doc/example/
trunk/Master/texmf-dist/doc/latex/modular/doc/example/octopus/
trunk/Master/texmf-dist/doc/latex/modular/doc/example/octopus/article.tex
trunk/Master/texmf-dist/doc/latex/modular/habitat.tex
trunk/Master/texmf-dist/doc/latex/modular/introduction.tex
trunk/Master/texmf-dist/doc/latex/modular/lifecycle.tex
trunk/Master/texmf-dist/doc/latex/modular/modular.pdf
trunk/Master/texmf-dist/doc/latex/modular/modular.tex
trunk/Master/texmf-dist/doc/latex/modular/modular_to_the_rescue.tex
trunk/Master/texmf-dist/doc/latex/modular/prerequisites.tex
trunk/Master/texmf-dist/tex/latex/modular/
trunk/Master/texmf-dist/tex/latex/modular/modular.sty
trunk/Master/tlpkg/tlpsrc/modular.tlpsrc
Added: trunk/Master/texmf-dist/doc/latex/modular/README-doc.md
===================================================================
--- trunk/Master/texmf-dist/doc/latex/modular/README-doc.md (rev 0)
+++ trunk/Master/texmf-dist/doc/latex/modular/README-doc.md 2017-05-01 21:56:14 UTC (rev 44142)
@@ -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`.
+
Property changes on: trunk/Master/texmf-dist/doc/latex/modular/README-doc.md
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: trunk/Master/texmf-dist/doc/latex/modular/README.md
===================================================================
--- trunk/Master/texmf-dist/doc/latex/modular/README.md (rev 0)
+++ trunk/Master/texmf-dist/doc/latex/modular/README.md 2017-05-01 21:56:14 UTC (rev 44142)
@@ -0,0 +1,45 @@
+```
+Copyright 2017 Daniel Thomas Sank (sank.daniel at 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).
+
Property changes on: trunk/Master/texmf-dist/doc/latex/modular/README.md
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: trunk/Master/texmf-dist/doc/latex/modular/article.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/modular/article.tex (rev 0)
+++ trunk/Master/texmf-dist/doc/latex/modular/article.tex 2017-05-01 21:56:14 UTC (rev 44142)
@@ -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}
+
Property changes on: trunk/Master/texmf-dist/doc/latex/modular/article.tex
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: trunk/Master/texmf-dist/doc/latex/modular/article_fail.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/modular/article_fail.tex (rev 0)
+++ trunk/Master/texmf-dist/doc/latex/modular/article_fail.tex 2017-05-01 21:56:14 UTC (rev 44142)
@@ -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}
+
Property changes on: trunk/Master/texmf-dist/doc/latex/modular/article_fail.tex
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: trunk/Master/texmf-dist/doc/latex/modular/content.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/modular/content.tex (rev 0)
+++ trunk/Master/texmf-dist/doc/latex/modular/content.tex 2017-05-01 21:56:14 UTC (rev 44142)
@@ -0,0 +1,3 @@
+\subimport*{./}{habitat.tex}
+\subimport*{./}{lifecycle.tex}
+
Property changes on: trunk/Master/texmf-dist/doc/latex/modular/content.tex
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: trunk/Master/texmf-dist/doc/latex/modular/coseoul_limitations.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/modular/coseoul_limitations.tex (rev 0)
+++ trunk/Master/texmf-dist/doc/latex/modular/coseoul_limitations.tex 2017-05-01 21:56:14 UTC (rev 44142)
@@ -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.
+
Property changes on: trunk/Master/texmf-dist/doc/latex/modular/coseoul_limitations.tex
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: trunk/Master/texmf-dist/doc/latex/modular/doc/content.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/modular/doc/content.tex (rev 0)
+++ trunk/Master/texmf-dist/doc/latex/modular/doc/content.tex 2017-05-01 21:56:14 UTC (rev 44142)
@@ -0,0 +1,5 @@
+\subimportlevel{./}{introduction.tex}{0}
+\subimportlevel{./}{prerequisites.tex}{0}
+\subimportlevel{./}{coseoul_limitations.tex}{0}
+\subimportlevel{./}{modular_to_the_rescue.tex}{0}
+
Property changes on: trunk/Master/texmf-dist/doc/latex/modular/doc/content.tex
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: trunk/Master/texmf-dist/doc/latex/modular/doc/example/octopus/article.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/modular/doc/example/octopus/article.tex (rev 0)
+++ trunk/Master/texmf-dist/doc/latex/modular/doc/example/octopus/article.tex 2017-05-01 21:56:14 UTC (rev 44142)
@@ -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}
+
Property changes on: trunk/Master/texmf-dist/doc/latex/modular/doc/example/octopus/article.tex
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: trunk/Master/texmf-dist/doc/latex/modular/habitat.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/modular/habitat.tex (rev 0)
+++ trunk/Master/texmf-dist/doc/latex/modular/habitat.tex 2017-05-01 21:56:14 UTC (rev 44142)
@@ -0,0 +1,3 @@
+\levelstay{Habitat}
+Octopuses live in the ocean.
+
Property changes on: trunk/Master/texmf-dist/doc/latex/modular/habitat.tex
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: trunk/Master/texmf-dist/doc/latex/modular/introduction.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/modular/introduction.tex (rev 0)
+++ trunk/Master/texmf-dist/doc/latex/modular/introduction.tex 2017-05-01 21:56:14 UTC (rev 44142)
@@ -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}.
+
Property changes on: trunk/Master/texmf-dist/doc/latex/modular/introduction.tex
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: trunk/Master/texmf-dist/doc/latex/modular/lifecycle.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/modular/lifecycle.tex (rev 0)
+++ trunk/Master/texmf-dist/doc/latex/modular/lifecycle.tex 2017-05-01 21:56:14 UTC (rev 44142)
@@ -0,0 +1,4 @@
+\levelstay{Life cycle}
+Octopuses start out as plankton, but can grow to
+hundreds of pounds.
+
Property changes on: trunk/Master/texmf-dist/doc/latex/modular/lifecycle.tex
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: trunk/Master/texmf-dist/doc/latex/modular/modular.pdf
===================================================================
(Binary files differ)
Index: trunk/Master/texmf-dist/doc/latex/modular/modular.pdf
===================================================================
--- trunk/Master/texmf-dist/doc/latex/modular/modular.pdf 2017-05-01 21:54:46 UTC (rev 44141)
+++ trunk/Master/texmf-dist/doc/latex/modular/modular.pdf 2017-05-01 21:56:14 UTC (rev 44142)
Property changes on: trunk/Master/texmf-dist/doc/latex/modular/modular.pdf
___________________________________________________________________
Added: svn:mime-type
## -0,0 +1 ##
+application/pdf
\ No newline at end of property
Added: trunk/Master/texmf-dist/doc/latex/modular/modular.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/modular/modular.tex (rev 0)
+++ trunk/Master/texmf-dist/doc/latex/modular/modular.tex 2017-05-01 21:56:14 UTC (rev 44142)
@@ -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}
+
Property changes on: trunk/Master/texmf-dist/doc/latex/modular/modular.tex
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: trunk/Master/texmf-dist/doc/latex/modular/modular_to_the_rescue.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/modular/modular_to_the_rescue.tex (rev 0)
+++ trunk/Master/texmf-dist/doc/latex/modular/modular_to_the_rescue.tex 2017-05-01 21:56:14 UTC (rev 44142)
@@ -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}
+
Property changes on: trunk/Master/texmf-dist/doc/latex/modular/modular_to_the_rescue.tex
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: trunk/Master/texmf-dist/doc/latex/modular/prerequisites.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/modular/prerequisites.tex (rev 0)
+++ trunk/Master/texmf-dist/doc/latex/modular/prerequisites.tex 2017-05-01 21:56:14 UTC (rev 44142)
@@ -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}.
+
Property changes on: trunk/Master/texmf-dist/doc/latex/modular/prerequisites.tex
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: trunk/Master/texmf-dist/tex/latex/modular/modular.sty
===================================================================
--- trunk/Master/texmf-dist/tex/latex/modular/modular.sty (rev 0)
+++ trunk/Master/texmf-dist/tex/latex/modular/modular.sty 2017-05-01 21:56:14 UTC (rev 44142)
@@ -0,0 +1,24 @@
+% Copyright 2017 Daniel Thomas Sank (sank.daniel at 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
+
Property changes on: trunk/Master/texmf-dist/tex/latex/modular/modular.sty
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Modified: trunk/Master/tlpkg/bin/tlpkg-ctan-check
===================================================================
--- trunk/Master/tlpkg/bin/tlpkg-ctan-check 2017-05-01 21:54:46 UTC (rev 44141)
+++ trunk/Master/tlpkg/bin/tlpkg-ctan-check 2017-05-01 21:56:14 UTC (rev 44142)
@@ -417,7 +417,7 @@
minted mintspirit minutes missaali
mkgrkindex mkjobtexmf mkpattern mkpic
mla-paper mlist mmap mnotes mnras mnsymbol
- moderncv moderntimeline modiagram modref modroman
+ moderncv moderntimeline modiagram modref modroman modular
mongolian-babel montserrat
monofill montex moodle
moreenum morefloats morehype moresize
Modified: trunk/Master/tlpkg/libexec/ctan2tds
===================================================================
--- trunk/Master/tlpkg/libexec/ctan2tds 2017-05-01 21:54:46 UTC (rev 44141)
+++ trunk/Master/tlpkg/libexec/ctan2tds 2017-05-01 21:56:14 UTC (rev 44142)
@@ -753,6 +753,7 @@
'mlbib', "die 'skipping, bib file names are too generic'",
'mnhyphn', "&MAKEmnhyphn",
'mnsymbol', "&MAKEflatten",
+ 'modular', "&MAKEflatten",
'mol2chemfig', "die 'skipping, python dependencies'",
'montex', "&MAKEflatten",
'morehelp', "die 'skipping, nonfree license'",
Modified: trunk/Master/tlpkg/tlpsrc/collection-latexextra.tlpsrc
===================================================================
--- trunk/Master/tlpkg/tlpsrc/collection-latexextra.tlpsrc 2017-05-01 21:54:46 UTC (rev 44141)
+++ trunk/Master/tlpkg/tlpsrc/collection-latexextra.tlpsrc 2017-05-01 21:56:14 UTC (rev 44142)
@@ -667,6 +667,7 @@
depend moderntimeline
depend modref
depend modroman
+depend modular
depend monofill
depend moodle
depend moreenum
Added: trunk/Master/tlpkg/tlpsrc/modular.tlpsrc
===================================================================
More information about the tex-live-commits
mailing list