From mboxrd@z Thu Jan  1 00:00:00 1970
X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on inbox.vuxu.org
X-Spam-Level: 
X-Spam-Status: No, score=-1.1 required=5.0 tests=DKIM_SIGNED,DKIM_VALID,
	DKIM_VALID_AU,MAILING_LIST_MULTI autolearn=ham autolearn_force=no
	version=3.4.4
Received: (qmail 29856 invoked from network); 1 Sep 2020 20:13:36 -0000
Received: from alyss.skarnet.org (95.142.172.232)
  by inbox.vuxu.org with ESMTPUTF8; 1 Sep 2020 20:13:36 -0000
Received: (qmail 27831 invoked by uid 89); 1 Sep 2020 20:13:57 -0000
Mailing-List: contact supervision-help@list.skarnet.org; run by ezmlm
Sender: <supervision@list.skarnet.org>
Precedence: bulk
List-Post: <mailto:supervision@list.skarnet.org>
List-Help: <mailto:supervision-help@list.skarnet.org>
List-Unsubscribe: <mailto:supervision-unsubscribe@list.skarnet.org>
List-Subscribe: <mailto:supervision-subscribe@list.skarnet.org>
List-Id: <supervision.list.skarnet.org>
Received: (qmail 27824 invoked from network); 1 Sep 2020 20:13:57 -0000
DomainKey-Signature: a=rsa-sha1; q=dns; c=nofws;
	h=X-Originating-IP:Date:From:To:Subject:Message-ID:In-Reply-To:References:MIME-Version:Content-Type:Content-Transfer-Encoding;
	s=default; d=troubleshooters.com;
	b=hSChZUeiTTyZlF+69yRy8js1gZ0DW788+yQWEA6+H/pC6zuqu+g9AJfA6i/U2RmQiqa3zfTjmwM6D24GJGNJc8eb1uJ3s2mPscPxan40ejLmBCstpGd99UBsaqdMwA+QIrweWJpfvc2tlxCkciDA+wzpjZkbSIMNUamnARNCDBo=;
DKIM-Signature: v=1; a=rsa-sha1; c=relaxed/simple; d=troubleshooters.com;
	s=default; t=1598991209; bh=9z8tG1EuJq7IYR9eoxO6gbcDeag=; l=2493;
	h=X-Originating-IP:Date:From:To:Subject:Message-ID:In-Reply-To:
	 References:MIME-Version:Content-Type:Content-Transfer-Encoding;
	b=klT93RfMM3+w9FGyq16wrFgv76LctIYY3eLdhg8pHbWTcNhHaE/05lk1ikOsS9c6Z
	 tyGPQIT/G88G2lzvVEhXrGHeYoScNIo4UKlBNhlCokOblWfBbjGXOstpynq8uRnB/t
	 +3n63Zidw+UoewwQN83iKzSmZGXD2kvx4Mb+h1S0=
X-Originating-IP: [184.90.157.212]
Date: Tue, 1 Sep 2020 16:13:27 -0400
From: Steve Litt <slitt@troubleshooters.com>
To: supervision@list.skarnet.org
Subject: Re: [request for review] Port of s6 documentation to mdoc(7)
Message-ID: <20200901161327.6f215b86@mydesk.domain.cxm>
In-Reply-To: <87d035yil3.fsf@ada>
References: <877dtgtu1z.fsf@ada>
	<emc6482779-5baf-404f-8eba-7ebe3b591742@elzian>
	<20200831160811.6zqdbyjyzk4bembt@mail.imca-cat.org>
	<ce4a975b-c861-74f4-c991-ddb6ba6370fa@lenzplace.org>
	<20200831191433.wbjh6wltyqhdv5hl@mail.imca-cat.org>
	<em5319e6fd-1081-4140-9af5-75537ebd0f40@elzian>
	<20200901063801.GA2158@CasperVector>
	<87d035yil3.fsf@ada>
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit

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