On 02Apr2018 01:29, sam varshavchik <mrsam(a)courier-mta.com> wrote:
Cameron Simpson writes:
>Well I was using Perl's POD format several years ago as my primary manual
>writing syntax, generates man and html. Good HTML to XHTML might be an easy
>transcription, I've not tried.
>
>Not specificly recommending POD, it was just a good syntax for the
>time. Quite low in features, but in many cases that is a good thing.
>
>I need to revisit this sometime myself, as I've got a project that
>will need man pages and fuller documentation as well.
Can POD generate an entire web site, with an automatically-generated
table of contents?
Not really. Like I said, low in features.
The Python people seem to like restructuredtext a lot; there's a tool called
sphinx for making whole sites from it, which seems liked.
https://www.libcxx.org is just one big Docbook document, with
navigation
footers. Doxygen generates the reference pages. Doxygen produces an XML file
with an index of all the reference pages. I run a custom XSLT stylesheet to
translate the index to URLs and entity references, which then gets included
into the main, paginated tutorial, generates links directly to the reference
pages.
I'm a big fan of good cross linking.
>But my basic point is that authoring syntax for humans needs to be
>light weight so that the source looks a fair bit like ordinary
>prose. Tools can always be written to generate specific outputs.
The more it looks like ordinary prose, the less metadata exists that
makes it possible to intelligently format it.
Sure, but a lot of prose doesn't need a great deal of special formatting.
I'm not sure we disagree very much here, except for my dislike of syntaxes with
heaps of punctuation everywhere, and XML falls into that slot for me.
Cheers,
Cameron Simpson <cs(a)cskk.id.au>