8

I am looking for packages useful for creating a documentation for a self written package.

I have found doc, but the documentation ltxdoc.pdf did not give me any useful example. Also I know of docstrip, but reading dtxtut.pdf was mostly scary for me. Preceding the whole documenting code with comments is not what I am looking for. (I know emacs has a special setup for docstrip, but I do not consider to switch to emacs)

I know that many packages are documented in different classes/templates. If some of them should be packaged and documented I would like to know about them.

Martin Scharrer
  • 262,582
Matthias Pospiech
  • 11,681
  • 2
    Did you see http://tex.stackexchange.com/questions/13028/how-do-i-document-my-style-files? – Joseph Wright Oct 06 '11 at 19:21
  • I searched this website, but found nothing related. However evene reading that post, all further links, including your blog post on dtx files I am still missing a good documentation (or any) of the doc class itsself. – Matthias Pospiech Oct 06 '11 at 21:00
  • Bear in mind that the .dtx format is as much about documenting the code itself as the user documentation. That said, texdoc doc seems to me to be a good place to start about the doc approach. Perhaps I should look at this on my blog. – Joseph Wright Oct 06 '11 at 21:03
  • Strange that texdoc knows a documentation, but ctan does not. But reading doc it seems to me that this is good for documenting the interface, but less documenting a tutorial for the enduser. Or should I first write all the documentation using additional classes such as listings and add the interface documentation using the doc package at the end? How is that done usually? Just a side not: doc looks very old fashioned. Especially compared to something like the documentation biblatex.pdf. – Matthias Pospiech Oct 06 '11 at 22:07

1 Answers1

7

Note that docstrip and doc/ltxdoc are used often together, but are not dependent on each other. The first is to extract files from a DTX file and strip the comments from it, the others for writing the package manual. You can use the doc package with other classes as ltxdoc as well.

Further classes for package documentation are:

However, the last two are written by package authors mainly for their own packages and are not (yet) supported for the use by others. ydoc is written by me, not to be considered finished and almost undocumented.

Martin Scharrer
  • 262,582
  • The codedoc documentation is written as if the author does not want to be considered seriously.

    Your package ydoc has unfinished documentation, but the existing one looks promising.

    xdoc is documented only for people knowing doc. At least I only see commands, but no example. Also it is quite old for describing itsself as experimental.

    dox suffers from the same problems as xdoc. However it seems to be still maintained.

    ltxdockit is not documented at all. Although I really like the authors package documentations.

    For the original doc package ctan does not list any documentation at all.

     – Matthias Pospiech Oct 06 '11 at 20:54
  • Nice summary :-) As I mentioned ydoc is unfinished and I didn't had much time or saw even reason to write much documentation for it. The \DescribeMacro and \Macro macros are useful to describe macros (first using a headline and then in the text). They take a very native syntax, e.g. \Macro\test{arg} is format as \test{arg}, add < > to get the special 〈 〉 angles, e.g. \Macro\test{<arg>} is turned into \test{〈arg〉}. For the rest see the DTX files of my other packages. They all use ydoc. – Martin Scharrer Oct 06 '11 at 21:03