On 02Apr2018 01:29, sam varshavchik <mrsam@xxxxxxxxxxxxxxx> 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@xxxxxxxxxx>
_______________________________________________
users mailing list -- users@xxxxxxxxxxxxxxxxxxxxxxx
To unsubscribe send an email to users-leave@xxxxxxxxxxxxxxxxxxxxxxx
