headers
Mark Weinem | 1 Apr 2007 21:18
Picon

Re: why XML?

On Sun, 1 Apr 2007, Greg A. Woods wrote:

> There's also the minor problem that some developers seem to be able to
> push in changes and new features without accompanying documentation.
> IMNSHO no code is worth committing until it is _fully_ documented, but
> at the very least those that are apparently reviewing it could at least
> call for minimal manual page entries and extensive, complete,
> cross-reference updates.  I'm not saying everything goes in without
> documentation, but it happens far too often it seems.

["XML is pain"]
> For example I had some edits to the pkgsrc guide document that I thought
> would be useful and interesting to everyone, but when it went XML I
> found it impossible to even continue to merge my changes from one
> quarterly branch to the next, let alone get them in shape for
> submission.
>
> I thought mdoc(7) provided all the necessary features for simultaneous
> publication of documentation in various forms, and in my estimation it
> is (luckily still) the most common way of authoring NetBSD
> documentation.  (perhaps even without counting the "man" pages)
>
> If folks want more structured (and truly structured) documentation then
> I could only recommend Lout (pkgsrc/textproc/lout) as it is light years
> beyond anything-TeX or troff-like and still light years beyond
> anything-ML too.
>
> I'd personally be happier with raw troff or even raw TeX than
> anything-ML.  There's nothing in the textual/documentation world more
> difficult and more complex to read, parse, or manage than *ML files.
(Continue reading)

Permalink | Reply | 1 comment |
headers
Mark Weinem | 1 Apr 2007 21:29
Picon

Re: Proposition for Releases page changes

On Sun, 1 Apr 2007, Greg A. Woods wrote:

> The thing that was originally lacking was an easy way to produce HTML
> output for online publishing in a form that permitted better structuring
> and cross referencing (not that plain text documents can't be used
> easily in any web browser).  However that problem was greatly relieved
> quite some time ago by improvements to groff and the html*.tmac macros.
> It seemed to me that further simple improvements to the html*.tmac stuff
> would have solved all the online publishing issues and then some.

Wow, back to nroff and troff/groff - what a triumph 
for the plan9 guys ;)

ciao, Mark

--

-- 
Mark Weinem
Jabber: weinem <at> jabber.cz
PGP-Key available
Permalink | Reply | 0 comments |
headers
James K. Lowden | 1 Apr 2007 22:51
Gravatar

Re: why XML?

Mark Weinem wrote:
> > I thought mdoc(7) provided all the necessary features for simultaneous
> > publication of documentation in various forms

How do you define a URL in mdoc?  Does it become an HREF anchor when
converted to HTML?  What about a GUI component?  How do you include a
graphic?  

> > If folks want more structured (and truly structured) documentation
> > then I could only recommend Lout (pkgsrc/textproc/lout) as it is light
> > years beyond anything-TeX or troff-like and still light years beyond
> > anything-ML too.

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

> > I'd personally be happier with raw troff or even raw TeX than
> > anything-ML.  There's nothing in the textual/documentation world more
> > difficult and more complex to read, parse, or manage than *ML files.

The evidence stands against you, though.  Many very large documentation
projects rely on DocBook.  

None of the systems you mention afaik have anything like DocBook
stylesheets.  I don't see separation of content from format.  Take the
<screen> tag for example (http://www.docbook.org/tdg/en/html/screen.html).
 How would you impose uniform formatting of screenshots unless every
instance of a screen is so designated?  

DocBook is not perfect for everything.  When my daughter's school papers
(Continue reading)

Permalink | Reply | 0 comments |
headers
haad | 1 Apr 2007 23:35
Picon
Gravatar

Re: why XML? (fwd)


Mark Weinem wrote:
> ---------- Forwarded message ----------
> Date: Sun, 1 Apr 2007 16:51:53 -0400
> From: James K. Lowden <jklowden <at> schemamania.org>
> To: netbsd-docs <at> NetBSD.org
> Subject: Re: why XML?
> 
> Mark Weinem wrote:
>>> I thought mdoc(7) provided all the necessary features for simultaneous
>>> publication of documentation in various forms
> 
> How do you define a URL in mdoc?  Does it become an HREF anchor when
> converted to HTML?  What about a GUI component?  How do you include a
> graphic?
> 
>>> If folks want more structured (and truly structured) documentation
>>> then I could only recommend Lout (pkgsrc/textproc/lout) as it is light
>>> years beyond anything-TeX or troff-like and still light years beyond
>>> anything-ML too.
> 
> I don't understand how you can recommend it.  The PDF backend is
> officially deprecated, and I see no HTML backend.
> 
>>> I'd personally be happier with raw troff or even raw TeX than
>>> anything-ML.  There's nothing in the textual/documentation world more
>>> difficult and more complex to read, parse, or manage than *ML files.
> 
> The evidence stands against you, though.  Many very large documentation
> projects rely on DocBook.
(Continue reading)

Permalink | Reply | 0 comments |
headers
Mark Weinem | 2 Apr 2007 00:41
Picon

Re: why XML?

James K. Lowden wrote:

> How do you define a URL in mdoc?  Does it become an HREF anchor when
> converted to HTML?  What about a GUI component?  How do you include a
> graphic?
>
>>> If folks want more structured (and truly structured) documentation
>>> then I could only recommend Lout (pkgsrc/textproc/lout) as it is light
>>> years beyond anything-TeX or troff-like and still light years beyond
>>> anything-ML too.
>
> I don't understand how you can recommend it.  The PDF backend is
> officially deprecated, and I see no HTML backend.
> [...]

sorry, the quotes are from Greg A. Woods. I'm only the forwarder, and i
have no detailed knowledge about Lout or groff.

How about "AsciiDoc"? It can produce HTML, PDF and DocBook document
types.

 	http://www.methods.co.nz/asciidoc/index.html

> The evidence stands against you, though.  Many very large documentation
> projects rely on DocBook.

Hm, if only many projects rely on but not all - what alternatives do
they use instead of DocBook?

> DocBook is neither an accident nor a fad.  It demonstrably yields good
(Continue reading)

Permalink | Reply | 22 comments |
headers
Greg A. Woods | 2 Apr 2007 01:07
X-Face
Favicon

Re: why XML?

At Sun, 1 Apr 2007 23:15:29 +0200 (CEST), Mark Weinem wrote:
Subject: Re: why XML? (fwd)
> 
> 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
(Continue reading)

Permalink | Reply | 4 comments |
headers
Greg A. Woods | 2 Apr 2007 01:25
X-Face
Favicon

Re: why XML?

At Mon, 2 Apr 2007 00:41:53 +0200 (CEST), Mark Weinem wrote:
Subject: Re: why XML? 
> 
> How about "AsciiDoc"? It can produce HTML, PDF and DocBook document
> types.
> 
>  	http://www.methods.co.nz/asciidoc/index.html

AsciiDoc reminds me far too much of being the same kind of hack as Henry
Spencer's AWF is:

	http://www.isc.org/sources/utils/text/awf.php

If one wants clearly readable, easily maintained, easily parsed,
structured documents suitable from everything from business cards to
entire books, then Lout really is the best thing I've seen to date (and
I've been looking at and for such tools for decades now).

HOWEVER, for NetBSD, with a _heavy_ investment already made in mdoc(7)
formatted documents, I would be quite happy to stick with that.  We
already have groff maintained in-tree, and we'll need it for the
foreseeable future anyway.  It's easy enough to use and it is very well
understood too.

--

-- 
						Greg A. Woods

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

Permalink | Reply | 20 comments |
headers
Przemysław Pawełczyk | 2 Apr 2007 08:36
Picon

7 points user's memo (was why XML?)

On Sun, 01 Apr 2007 19:25:32 -0400
"Greg A. Woods" <woods <at> planix.com> wrote:

> If one wants clearly readable, easily maintained, easily parsed,
> structured documents suitable from everything from business cards to
> entire books, then Lout really is the best thing I've seen to date
> (and I've been looking at and for such tools for decades now).
>
> HOWEVER, for NetBSD, with a _heavy_ investment already made in mdoc(7)
> formatted documents, I would be quite happy to stick with that.  We
> already have groff maintained in-tree, and we'll need it for the
> foreseeable future anyway.  It's easy enough to use and it is very
> well understood too.
Hi,

The whole disscusion on NetBSD documentation was branched into
several topics nearly from the begining. Now I understand we went
thru following salient point:

1) wrong WWW layout
2) outdated docu-pages
3) weak cooperation with community
4) unefficient docu-page creation tools

A lot of steam was released but we are still in the same dock. This way
we can argue for ages.

Could someone summerize what convenient tools for XML (present),
nroff/mdoc (former), and Lout (recommended) formats available for
NetBSD user willing to write docu-pages? When I write docu-pages I
(Continue reading)

Permalink | Reply | 18 comments |
headers
haad | 2 Apr 2007 11:31
Picon
Gravatar

Re: 7 points user's memo (was why XML?)


Przemysław Pawełczyk wrote:
> On Sun, 01 Apr 2007 19:25:32 -0400
> "Greg A. Woods" <woods <at> planix.com> wrote:
> 
>> If one wants clearly readable, easily maintained, easily parsed,
>> structured documents suitable from everything from business cards to
>> entire books, then Lout really is the best thing I've seen to date
>> (and I've been looking at and for such tools for decades now).
>>
>> HOWEVER, for NetBSD, with a _heavy_ investment already made in mdoc(7)
>> formatted documents, I would be quite happy to stick with that.  We
>> already have groff maintained in-tree, and we'll need it for the
>> foreseeable future anyway.  It's easy enough to use and it is very
>> well understood too.
> Hi,
> 
> The whole disscusion on NetBSD documentation was branched into
> several topics nearly from the begining. Now I understand we went
> thru following salient point:
> 
> 1) wrong WWW layout

> 2) outdated docu-pages
> 3) weak cooperation with community
> 4) unefficient docu-page creation tools

4) this is your opinion from my point of view they are efficient.

> A lot of steam was released but we are still in the same dock. This way
(Continue reading)

Permalink | Reply | 0 comments |
headers
Przemysław Pawełczyk | 2 Apr 2007 12:07
Picon

Re: 3.1 CVS tag question

On Mon, 2 Apr 2007 14:00:35 +0200
Geert Hendrickx <ghen <at> telenet.be> wrote:

> On Mon, Apr 02, 2007 at 12:42:37PM +0100, Matthias Scheler wrote:
> > On Mon, Apr 02, 2007 at 06:19:12AM -0500, J.D. Bronson wrote:
> > > netbsd-3-1
> > > or
> > > netbsd-3-1-base
> > >
> > > Or, are these the same?
> >
> > No. "netbsd-3.1" is NetBSD 3.1.x branch. "netbsd-3-1-base" is the
> > tag which marks where the "netbsd-3-1" branch was created.
>
> No, netbsd-3-1-RELEASE is the base tag for the netbsd-3-1 branch.
>
> 	Geert

Great!

What to say about fresh user without much unix background...
Excellent example of rocket science where simple sling would suffice.

Thank you Gentlemen. It's high time to think the NetBSD over.

Regards,
pp

--
Przemysław Pawełczyk <pp <at> kv.net.pl>
(Continue reading)

Permalink | Reply | 25 comments |

Gmane