From: Steve Litt <slitt@troubleshooters.com>
To: supervision@list.skarnet.org
Subject: Re: [request for review] Port of s6 documentation to mdoc(7)
Date: Tue, 1 Sep 2020 16:13:27 -0400 [thread overview]
Message-ID: <20200901161327.6f215b86@mydesk.domain.cxm> (raw)
In-Reply-To: <87d035yil3.fsf@ada>
On Tue, 01 Sep 2020 19:03:36 +1000
Alexis <flexibeast@gmail.com> wrote:
> Casper Ti. Vector <caspervector@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
next prev parent reply other threads:[~2020-09-01 20:13 UTC|newest]
Thread overview: 30+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-08-30 8:30 Alexis
2020-08-30 9:10 ` eric vidal
2020-08-31 6:56 ` Alexis
2020-08-30 10:01 ` Laurent Bercot
2020-08-31 7:01 ` Alexis
2020-08-31 11:04 ` Laurent Bercot
2020-08-31 14:29 ` Guillermo
2020-09-01 10:00 ` possible s6-rc redesign (was: [request for review] Port of s6 documentation to mdoc(7)) Laurent Bercot
2020-09-01 19:24 ` possible s6-rc redesign mobinmob
2020-09-01 22:16 ` Dudemanguy
2020-09-01 22:20 ` Laurent Bercot
2020-09-02 9:41 ` mobinmob
2020-09-02 12:14 ` Laurent Bercot
2020-09-01 23:14 ` possible s6-rc redesign (was: [request for review] Port of s6 documentation to mdoc(7)) Steve Litt
2020-08-31 16:08 ` [request for review] Port of s6 documentation to mdoc(7) J. Lewis Muir
2020-08-31 17:45 ` Jason Lenz
2020-08-31 19:14 ` J. Lewis Muir
2020-08-31 20:51 ` Laurent Bercot
2020-09-01 6:38 ` Casper Ti. Vector
2020-09-01 9:03 ` Alexis
2020-09-01 9:20 ` Casper Ti. Vector
2020-09-01 10:02 ` Alexis
2020-09-01 10:15 ` Casper Ti. Vector
2020-09-01 20:13 ` Steve Litt [this message]
2020-09-02 0:50 ` Alexis
[not found] ` <20200901063801.GA2158@caspervector>
2020-09-01 10:11 ` Laurent Bercot
2020-09-01 11:28 ` Casper Ti. Vector
2020-09-01 11:55 ` Alexis
2020-08-31 19:36 ` Laurent Bercot
2020-08-31 19:58 ` J. Lewis Muir
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20200901161327.6f215b86@mydesk.domain.cxm \
--to=slitt@troubleshooters.com \
--cc=supervision@list.skarnet.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).