Comprehensive TeX Archive Network

Direc­tory macros/latex/contrib/xdoc

README for the xdoc and docindex packages.

The standard LaTeX doc package is well-known to all LaTeX hackers. 
Without its support for the .dtx-file style of literate programming, 
the TeX world would probably be much more plagued by the horrors of
poorly commented and mysterious code than it is today. The past good 
decade that doc has been with us has been -- good. But even the sun 
has spots; doc is an old package and, as old code often tends to do, 
it breaks if you try to bend it into doing something new. The xdoc 
package is (or rather is meant to be) a rewrite from scratch 
which both can take a lot more bending and is ready for LaTeX2e*.

What exists so far is only xdoc2: the "second prototype" for the xdoc 
package. xdoc2 is not a complete rewrite of doc, but rather an add-on 
to doc which reimplements many of its mechanisms (more precisely those 
mechanisms which I think should be possible to "bend" into doing new 
things, but have found to be fixed to their present behaviour) and 
provides a few new features of its own. Even though xdoc2 is a 
prototype and some of the code in it is experimental, I consider it to 
be safe enough to build productive applications on, as I intend to 
keep xdoc2 available even after the final xdoc package is released.

Among the features of xdoc2 are:
  - new commands for describing things (cf. \DescribeMacro) and a
    package/class writer's interface for defining new such commands.
  - new environments for defining things in (cf. the macro 
    environment) and a package/class writer's interface for defining 
    new such environments.
  - support for two-sided document designs.
  - support for external cross-referencing.
  - improved sorting of macros, with support for defining prefixes
    that should be ignored when sorting.
  - support for CVS-style version numbering.
The other new features are of little interest to the mere user, but 
they may be ever so useful to those who are in the habit of hacking 
doc. Here we have for example:
  - basic commands implementing a robust "string" datatype.
  - an abstract command interface for making index entries;
    this would simplify supporting a different index sorting

Besides xdoc2, there are also the docindex/docidx2e packages. These 
provide mechanisms for a more flexible formatting of the index and list of 
changes than is possible with the mechanisms for this in the doc package. 
In particular docindex/docidx2e provides for automatic collapsing of 
trivial index levels, something which often happens in automatically 
generated multilevel indices such as the list of changes. The reason there 
are two packages is that docindex is a LaTeX2e* package, whereas docidx2e 
is a "downgraded" variant which runs on a normal LaTeX2e installation. 
Both do however follow the same internal logic.

The files in this directory are:

README.txt    - this file
docindex.dtx  - the source for the docindex and docidx2e packages
docindex.ins  - the docstrip installation script for the docindex and 
                docidx2e packages
xdoc2.dtx     - the source for the xdoc2 package
xdoc2.ins     - the docstrip installation script for the xdoc2 package
xdocdemo.tex  - a document which demonstrates some of the features in
                the xdoc2 package

Lars Hellstr\"om

Down­load the con­tents of this pack­age in one zip archive (915.9k).

xdoc – Ex­tend­ing the LaTeX doc sys­tem

Xdoc is a project to rewrite the im­ple­men­ta­tion of the LaTeX doc pack­age (in a broader sense) to make its fea­tures more gen­eral and flex­i­ble. For ex­am­ple, where doc only pro­vides com­mands for doc­u­ment­ing macros and en­vi­ron­ments, xdoc also pro­vides com­mands for sim­i­larly doc­u­ment­ing pack­age op­tions and switches. This is fur­ther­more done in such a way that it is very easy to add more such com­mands for doc­u­ment­ing things, such as e.g., tem­plates (an im­por­tant con­cept in the fu­ture LaTeX3) and pro­gram com­po­nents for other lan­guages (func­tions, classes, pro­ce­dures, etc.). A side ef­fect is that many mi­nor bugs in doc are fixed.

The de­sign aims to take ad­van­tage of many still ex­per­i­men­tal fea­tures of fu­ture ver­sions of LaTeX, but since these are nei­ther rea­son­ably sta­ble nor widely avail­able, the con­fig­u­ra­tion in­ter­faces and pack­age au­thor com­mands of xdoc are likely to change. To still pro­vide a sta­ble in­ter­face for other pack­ages to build upon, the ac­tual pack­age names in­clude a "ma­jor ver­sion num­ber" of sorts. The drop-in re­place­ment pack­age for stan­dard doc is xdoc2; it re­quires noth­ing out­side stan­dard LaTeX2ε.

The docin­dex/do­cidx2e pack­age changes the in­dex and list of changes type­set­ting so that none of the for­mat­ting has to be con­trolled via the in­dex style file. The docin­dex pack­age pro­vides con­trol of for­mat­ting via tem­plates (nice in­ter­face, but re­quires sev­eral ex­per­i­men­tal pack­ages), whereas the do­cidx2e pack­age has tra­di­tional raw macro in­ter­faces and works with stan­dard LaTeX2ε.

Li­censeThe LaTeX Project Public Li­cense
Main­tainerLars Hell­ström
Con­tained inTeX Live as xdoc
MiKTeX as xdoc
Topics macros and tools for prepar­ing doc­u­men­ta­tion
Guest Book Sitemap Contact Contact Author