Subject: Re: why XML?
To: NetBSD Documentation Discussion List <netbsd-docs@netbsd.org>
From: Greg A. Woods <woods@planix.com>
List: netbsd-users
Date: 04/01/2007 19:07:14
--pgp-sign-Multipart_Sun_Apr__1_19:07:05_2007-1
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: quoted-printable

At Sun, 1 Apr 2007 23:15:29 +0200 (CEST), Mark Weinem wrote:
Subject: Re: why XML? (fwd)
>=20
> How do you define a URL in mdoc?

UTSL:

.Lk href [ anchortext/punc ] ...


>  Does it become an HREF anchor when
> converted to HTML?

Of course.

(cross references for manual pages sort of work too, though they
currently make certain hard-coded assumptions about the layout of the
installed pages and documentation)



>  What about a GUI component?

What's a GUI component?  Why would NetBSD documentation contain anything
like a "GUI component?"


>  How do you include a
> graphic?

Well presumably the same way you would do so in any mdoc(7) document
now, though likely you'd have to have multiple image formats for the
same displays and some wrapper scripts/makefiles to maintain them and
install them in the right places when publishing your document in
different formats.


Keep in mind that mdoc2html is a bit of a hack with nroff, not troff.

There's also "groff -Thtml" for directly generating HTML from any macro
package (see grohtml(1)), and it (apparently) works better with tbl and
eqn, and perhaps grap could work well with it too.  However I'm not
nearly so familiar with using it to do anything useful.  I'm not nearly
so enamored with its default look either, however no doubt these issues
are relatively easily solved.


> I don't understand how you can recommend it.  The PDF backend is
> officially deprecated, and I see no HTML backend.

Officially one should never create PDF directly, IMHO, regardless of
whether you're using Lout or any other typesetting system.  Use
ghostscript or similar to generate a PDF from the postscript.

Publishing HTML isn't typically all that important for Lout users --
they want the control that comes from full typeset output, thus they
generate PS and then maybe convert it to PDF for online publishing.

I'm not a big fan of any of the available PDF readers, but perhaps if
there were a good open-source one that had better searching and browsing
capabilities with multiple open documents then it would be the best
format for online publishing of NetBSD documentation too.


> The evidence stands against you, though.

I don't know where you get that idea.  The evidence is quite clearly in
my favour.  Just look at the lines of code, the inherent parser
complexity, and the CPU cycles necessary for handling anything like
SGML, let alone XML.  Even Lout can sometimes be smaller and faster by
comparison.  Others have already made this point much better than I can
in the predecessor to this thread.


>  Many very large documentation
> projects rely on DocBook.

That's clearly not what I was talking about.  Just because people can
push a bull through a china shop doesn't mean they should.  But, they
make their own beds....


> DocBook is neither an accident nor a fad.

Sadly that is true.

However if you don't think Groff (or Lout, for that matter) is actively
used and maintained, then please look again.

--=20
						Greg A. Woods

H:+1 416 218-0098 W:+1 416 489-5852 x122 VE3TCP RoboHack <woods@robohack.ca>
Planix, Inc. <woods@planix.com>       Secrets of the Weird <woods@weird.com>

--pgp-sign-Multipart_Sun_Apr__1_19:07:05_2007-1
Content-Type: application/pgp-signature
Content-Transfer-Encoding: 7bit

-----BEGIN PGP SIGNATURE-----
Version: PGPfreeware 5.0i for non-commercial use
MessageID: NPjU77ynvQ3+XBBWtZzXNiz4aX1Cl6AC

iQA/AwUBRhA7HmZ9cbd4v/R/EQKT7QCfZI5YMgLhL6T7ecyY4g+ikzZesgUAoOub
JBA/ePjBdik+7vqMPySPsjGF
=7GuG
-----END PGP SIGNATURE-----

--pgp-sign-Multipart_Sun_Apr__1_19:07:05_2007-1--