OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-apps message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Re: [docbook-apps] documenting code

John W. Shipman wrote:
> +-- Dave Pawson:
> | Yet again, quote
> |
> | A small Python script extracts one or more source files from
> | the document,  and these are the executable form of the program.
> | /quote
> |
> | That seems wrong John?
> +--
> What exactly is wrong with that?  I have a Makefile set up
> so I type:
>     make code

Wrong as in non generic, tailored to your usage?
Looking at the Python it seems functionally equal
to an xslt transform?

> and it runs my Python script, which extracts the source files.
> When I say they are the executable form of the program, they are
> exactly that for Python, Relax NG, and XSLT.  For a compiled
> language there would clearly be a compile step.  Sorry I didn't
> mention that, but I haven't used any compiled languages for
> over ten years.

No, source seems 'right' for this.

> +--
> | Another problem I have, a long command line, e.g. calling
> | java, saxon for a transform,
> | docbook has no
> |
> | <line>java -cp .....
> | <linebreak/>main.class
> | <linebreak/>param1
> | etc
> |
> | To enable XSLT to re-build a single line from one
> | split, for the sake of convenience?
> +--
> This is another problem I haven't encountered.  I usually keep my
> lines short (75 characters for the current toolchain). 

Not possible when the resultant command line needs to be on one line.
Embedded markup allows for better documentation. Again, easy
enough to strip out using XSLT.

> Another reply on this thread said that they prefer to keep the
> documentation inside the code, rather than the literate approach
> wherein the code is inside the documentation. 

I prefer XML to wrap code simply to enable XSLT processing.

  The drawback to
> their approach is that you need a different extractor for each
> language. 

Or a more GP 'filter'. XSLT seems optimum to me.


Dave Pawson

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]