[BusyBox] Re: A small step toward auto-generating documentation...

[Mark Whitley]

On Fri, Feb 09, 2001 at 12:23:55PM -0800, Larry Doolittle wrote:
> Mark -
> 
> > Hmm... I hadn't really given any thought about going the other way.
> > Personally, I think it would be safer to generate docs from code rather
> > than try to generate code from docs. It would also mean no further
> > dependencies on compiling the code. (The less build dependencies, the
> > better, I think.)
> 
> You have a point.  If the documentation tools crash, a customer can always
> read the docs on the web.

That's kinda what I was thinking. Along these same lines, if we keep usage.c
up to date, the customer can always just look at usage.c in lieu of any other
marked-up documentation.

> > What do you think would be the advantage(s) of going the other way;
> > docs->code?
> 
> It might be easier to strip out formatting instructions that
> don't render in ASCII, than have heuristics to add them for
> a richer environment like SGML.
> 
> I guess usage.c could have tag-like features encoded in such
> a way as to be invisible when run through cpp during the primary
> build, like
> 
> #define EMPH(x) x
> const char chmod_usage[] =
> 	"Usage: chmod [" EMPH("-R") "] MODE[,MODE]... FILE..."

My preference would just be to use the mystical-magical power of Perl regexes
to do this. There are already enough fairly well-followed convetions to make
this feasible.

Something along these lines:

	$line =~ s/($applet\s+\[)(.*?)(\].*$)/\1<emphasis>\2</emphasis>\3/;

> You could even use cpp to help you convert this to SGML:
> #define EMPH(x) "<emphasis>" x "</emphasis>"
> 
> Snort.  Did we just find the ultimate document formatting tool?  cpp?

Doc formatting? That's *nuthin'*! I'll betcha we could make a
fully-functional, Turing-complete imperative programming language using just
the pre-processo... Oh, wait.

:-)

Mark Whitley
markw at lineo.com