On Tue, 01 Sep 2020 19:03:36 +1000
Alexis <flexibeast_at_gmail.com> wrote:
> Casper Ti. Vector <caspervector_at_gmail.com> writes:
>
> > * We negotiate a HTML schema your documentation can be written
> > in, which
> > is based on current documentation; existing HTML documentation
> > will be
> > converted to the schema, with minimised changes.
>
> On the basis of my current experiences, it would be No Small Task
> to convert the current, presentationally-based, HTML documentation
> to markup that's sufficiently semantic to enable it to be
> mechanically converted to mdoc/roff.
Depends on how the HTML is written. You can take any
Troubleshooters.Com web page authored new in the past five years, run
it through an XML parser, and come up with all-styles, no appearance
code. All my appearance is via CSS, none is via tags in the <body/>.
It's my very strong opinion that, in a conversion to a different output
format, the CSS should be just dumped on the floor, and LaTeX or
Docbook or whatever styles should be hand-authored appropriately for
the output format. With no-appearance-in-body HTML, it's very easy
during conversion to make a list of all referenced styles, making
authoring of such style-to-appearance conversion easy.
So it all depends on how the HTML was written. If it was crafted by a
styles-aware person using CSS to translate styles to appearance, and
having no appearance info in <body/>, and if the HTML is well formed
XML (which is just fine for HTML5), then the conversion is trivial. If
it's thrown together, catch as catch can HTML, then Alexis is right,
programmatic conversion would be a mess. If the HTML was made by one of
those GUI WYSIWYG HTML editors, then the HTML is absolute junk and it's
best to start anew.
See
http://troubleshooters.com/linux/unbound_nsd/unbound.htm for an
example of no-appearance-in-body HTML5 document.
By the way, if any of you is interesting in helping create an
all-styles, no appearance, quick authoring documentation language,
please contact me offlist. I have the beginnings of one, but was unable
to do the whole thing myself.
In this post I express no opinion whether this should or shouldn't be
done. All I'm saying is don't assume, sight unseen, that the current
HTML can't easily be converted to semantic LaTeX or Docbook or whatever.
SteveT
Steve Litt
Autumn 2020 featured book: Thriving in Tough Times
http://www.troubleshooters.com/thrive
Received on Tue Sep 01 2020 - 20:13:27 UTC