text/plain; charset="iso-8859-1"; format=flowed
Tue, 8 Sep 2009 21:08:53 +0200
At 00:58 02.09.09, Manuel Pégourié-Gonnard wrote:
>I prefer package code to be the primary content and documentation to be
>extracted from comments. I find it much easier for changing the code and
>testing it without needing ot extract it first. (Same problem as dtx.)
At 16:15 08.09.09, Robin Fairbairns answered an answer to the previous as
>i don't mind dtx, particularly (i've been writing it for >15 years, and
>my fingers wander to the necessary groove without prompting).
>however, there are quite a few (significant) packages on ctan that have
>lots of documentation as comments only. if i could take one such and
>produce a useful printable document, i could improve the quality of user
>support quite a bit.
>(i've dallied with editing the comments into a separate .tex file.
>this works, but is time-consuming, and tempts one into editorial work.)
Indeed I hope to do this (including automatic ASCII to LaTeX) with
'makedoc' and plan to apply to the development fund for it. It works with
my own preferred ASCII style to some extent now, but other authors use
different styles. At present only lines starting with `%% ' are considered
"smoothly" typesettable comments, in order to allow "commenting out" of
code that then is to be typeset verbatim. With 'wiki.sty' I have also
implemented some ASCII representation of list-like environments, but
package authors have different ideas for such ASCII representations.
'makedoc' must be made adaptable to such styles, and it needs some tidying
to be useful before.
My first focus is on Donald Arseneau's packages. I think 'natbib' has
"internal" documentation of this style, PiCTeX as well, but such packages
seem to have some other well-typeset documentation already.
Wait what happens ...