Cameron Simpson writes:
On 01Apr2018 23:55, sam varshavchik <mrsam@xxxxxxxxxxxxxxx> wrote:Cameron Simpson writes:There are plenty of popular human friendly formats out there like markdown and restructured text etc which render to various output formats.Which "human friendly" format can I use which already has tools to generate both well-formed XHTML and man-compatible troff content, from the same source?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? 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.
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.
Attachment:
pgptTDhCZ7soC.pgp
Description: PGP signature
_______________________________________________ users mailing list -- users@xxxxxxxxxxxxxxxxxxxxxxx To unsubscribe send an email to users-leave@xxxxxxxxxxxxxxxxxxxxxxx
