TUGboat, Volume 0 (9999), No. 0

preliminary draft, August 6, 2018 0:27

?1

What’s to stay, what’s to go — A quarter
century of doc
Frank Mittelbach
Abstract

I believe that the time is ripe for significantly
better documentation of programs, and that
we can best achieve this by considering
programs to be works of literature. Hence,
my title: "Literate Programming."

In this talk I will re-examine my poor attempts at
Literate Programming and how they have shaped(for the better or worse) the LATEX world in the past
decades.
It’s about time to rethink some of the concepts
invented back then—but can we still evolve?

Don Knuth 1984

Intropmb --- poor man’s bold

stripteasenext quarter century

Slide #2

I believe that the time is ripe for significantly
better documentation of programs, and that
we can best achieve this by considering
programs to be works of literature. Hence,
my title: "Literate Programming."
Don Knuth 1984

Intro30 years
pmb --- poor man’s bold

striptease

doc.sty 1.0 (1988)

docstrip 2.0 (1991)

next quarter century

introduced .dtx and .ins

doc.sty 2.0 (1998)

stayed virtualy unchangedfor 2 decades

Slide #3

What's to stay, what's to go

hypdochyperref support

DoX

new document elements
usually also
doc elements

xdoc, xdoc2

A quarter century of doc

ydoc

some offsprings

Frank Mittelbach

misc. ideas

docmfpgmdoc...

Rio, July 2018l3doc (class)support for expl3, e.g. @@ notation, etc
l3docstrip

Slide #1

preliminary draft, August 6, 2018 0:27

Slide #4

preliminary draft, August 6, 2018 0:27

?2preliminary draft, August 6, 2018 0:27

Was it successful?

TUGboat, Volume 0 (9999), No. 0

yes

Old sources should be correctly processed
without the need for changes (99.9%)

not reallyquestionable interfaces

Markup up for additional doc elements should beprovided (in a flexible way)

Was it good?
missing interfaces

Evaluations

false friend

Goals for a newversion

hyperref support should be out of the box

Overall conclusion?

Slide #5

Slide #8

how many spaces have to be there?

not reallyprovides automatic hyperlinks for version 2% \end{macrocode}

questionable interfaces

no (real) support for anything other than Macroreusemissing interfaces
Env came later but was never fully functional
Was it good?

perhaps

eventuell

hyperref support

hypdocnew document elements

DoXtalvez

eventually schließlich

finalmente

false friend

revamp\StopEventuallycannibalizationAE
occasionallysurprise: this „friend“ survived in most rewrites eventhose that suggested command renames

eventualmente

basic concept for doc elements is sound, but
I don’t like the actual interface -> revamp

the Portugese variant

Slide #6

Was it successful?

Slide #9yes

not reallyquestionable interfaces
Was it good?
missing interfaces

false friendEvaluationsa „bad“ standard in a certain place
may be better than none
Overall conclusion?

\RenewDocElement[,macrolike = false,toplevel = false,idxtype=% env.
,idxgroup = Package environments,printtype = \textit{env.}]{Env} {environment}
new document elements\NewDocElement[,macrolike = false,toplevel = false,idxtype= % counter,idxgroup = LaTeX counters\actualchar\LaTeX{} counters,printtype = \textit{counter}]{LaTeXCounter} {lcounter}revampbasic concept for doc elements is sound, but
I don’t like the actual interface -> revampchanging a standard is not easy (if even possible)

Slide #7

preliminary draft, August 6, 2018 0:27

Slide #10

preliminary draft, August 6, 2018 0:27

TUGboat, Volume 0 (9999), No. 0

preliminary draft, August 6, 2018 0:27

?3

how to best integrate hyperref functionality

integrate short new user commands?

how to handle encap config commands

Problems to solve

Slide #11

integrating hypdoc has the danger ofhyperref option clash
maybe the kernel needs to provide anoption clash handler interface

how to best integrate
hyperref functionality

The Endalternatively or in addition doc could provide a
config file in which one can turn of/on features
make hyperref=false the default

adding short new commands for use in
documentation has the danger ofconflicting with existing definitions\meta

integrate short new usercommands?

Problems to solve\cs
provide option shorthands\main + \usage exist
how to handle encap
config commands\code or \codeencap?

Slide #14

change everything to \...encap

Slide #12

The slides have been retrospectively constructed fromthe mindmap used during the presentation.
Test version available at:github.com/FrankMittelbach/fmitex(doc-v3)

comments/tests welcome Frank Mittelbach
https://www.latex-project.org

plans to integrate the new version in 2018

apply the new rollback concept for packages

as a result the core kernel documentation
would require the use of expl3
hyperlink support will probably still stay
optional

The way forward

Slide #13

preliminary draft, August 6, 2018 0:27

preliminary draft, August 6, 2018 0:27