Cameron Simpson writes:
On 01Apr2018 23:55, sam varshavchik <mrsam(a)courier-mta.com>
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.