NetBSD Documentation Framework - how to do it

"James K. Lowden" <jklowdenschemamania.org> wrote:
> Mike M. Volokhov wrote:
> > "James K. Lowden" <jklowdenschemamania.org> wrote:
> > > Mike M. Volokhov wrote:
> > > > This can (and is) done in the following
forms:
> > > > 
> > > > 	- web-site
> > > > 	- documents for offline browsing
> > > > 	- documents for printing (including
books)
> > > > 	- other forms (not addressed here):
verbal, prezos, ads...
> > > > 
> > > > Can you use Jade as solution for the
first three? Yes, but it has
> > > > not been adopted for this yet. 
> > > 
> > > I'm not sure what you mean by "it has
not been adopted for this yet." 
> 
> I wasn't trying to be combative, Mishka.  I was hoping
you would explain
> what you meant by "not adopted". 

I wasn't either.  

I'll try directly answer on your question. Both good
web-site and
good printed book have something that differs them from
their bad
made "colleagues". There are easy to read and
understand content,
none of grammatical and logical errors, smart navigation,
eye candy
design, and many more. It's easy to see that right now we
have a
bad docs.

On the back side of this "moon" we have a
documentation workflow.
Important features here include easy typesetting, effective
collaborative authoring, convenient language translation
procedures,
and flexible and easy to use tools for media preparation.
And
situation here is more interesting. We have a tools
available on
OSS "market", for example, Jade. But with terrible
workflow we
can't made good books or site. So yes, tools was not adopted
enough
for NetBSD.

If we will take Jade again, there is no jade-based framework
to
build perfect books (correct me please if I'm wrong; but see
above).
Although this is quite possible. So Jade was not adopted at
all.
To be clear here I'm pretty sure that with current DocBook
stylesheets
you can not produce good book - they are need further
customization.

> > Please compare the following two guides:
> > 
> > 	- http://www.ua.netbsd.org/guide/download/netbsd-en.pdf.gz

> > 	- http://www.oreilly.com/catalog/bsdhks/chapter/hack67.pdf

> 
> Done. I think your point is that Dru's book is more
visually attractive? 
> And that you would like to see us using a toolchain
that produced
> similarly attractive works?  And you doubt DocBook is
the answer?  
> 
> Using one source document to produce a website and a
book requires
> compromises.  If your goal is "most
attractive", you have to be willing to
> use two sources.  If your goal is "more attractive
than today", you could
> stick with DocBook and tailor it both with stylesheets
and some
> output-specific sections.  

What I'm trying to do is to create documentation framework
build
on top of well defined workflow. And yes, the goal is
"most attractive
ever". I'll hope we all together can do this with
single source
documents 

--
Best regards,
Mishka.

On Thu, 14 Dec 2006, Mike M. Volokhov wrote:
> If we will take Jade again, there is no jade-based
framework to
> build perfect books (correct me please if I'm wrong;
but see above).

Just an idea: what do you think of TeX?
Gives print and (with latex2html) HTML.

As an alternative, I've made good experiences with 
http
://www.feyrer.de/Texts/Own/NWF/nwf_toc.html.

No, it's not XML, but so what.


  - Hubert

> Just an idea: what do you think of TeX?
> Gives print and (with latex2html) HTML.
> 
> As an alternative, I've made good experiences with
> http
://www.feyrer.de/Texts/Own/NWF/nwf_toc.html.
> 
> No, it's not XML, but so what.

I have used latex2html a lot.

I heard it is unmaintained.

Another tool is TeX4ht
http://w
ww.cse.ohio-state.edu/~gurari/TeX4ht

and tth:
http://hutchinso
n.belmont.ma.us/tth/

And hevea:
h
ttp://pauillac.inria.fr/~maranget/hevea/index.html

Last I heard XML to print usually use latex.

I think staying with XML is fine for our website. I have no
advice either 
way.

I do use latex a lot especially with LyX for letters, course
books, other 
books, etc.

Hubert Feyrer <hubertfeyrer.de> wrote:
> On Thu, 14 Dec 2006, Mike M. Volokhov wrote:
> >If we will take Jade again, there is no jade-based
framework to
> >build perfect books (correct me please if I'm
wrong; but see above).
> 
> Just an idea: what do you think of TeX?
> Gives print and (with latex2html) HTML.
> 
> As an alternative, I've made good experiences with 
> http
://www.feyrer.de/Texts/Own/NWF/nwf_toc.html.
> 
> No, it's not XML, but so what.

Some *TeX is certainly an option. But I don't think LaTeX
can easily
substitute XML here. TeX was designed to deal with
typesetting of
complex pages, and LaTeX bring some high level structures.
But it
still the typographic system by nature.

Also, it's good to store content and representation
separately.
Single source, multiple representations, data recombination
-
just to mention few advantages. And surely tools should made
this
possible. Looks like XML clearly wins here.

But "XML Way" have some severe cons.
Human-discouraging format for
source files and hard preprint process are possible most
annoying.
Both much more userfriendly with TeX. We can solve the
second one,
but to simplify file format we should insert something other
into
workflow and did the trick (back to SGML?).

As for me, using TeX based tools to produce HTML looks like
a quest,
but I'm not experienced here. So if someone (you, Jeremy, or
anybody
else) can discover this, it would be really good. Please
note, that
first of all we need to setup requirements. For example,
website
should support skins or something similar; data
consolidation (RSS)
and redistribution (news items) should be supported as well.
And
only after that made decision is TeX (and any other tool)
appropriate
here or not.

--
Mishka


P.S. To keep all things together I've occuped BSDDF
namespace on
NetBSD Wiki - http://wi
ki.netbsd.se/index.php/BSDDF:Main. Please
feel free to put all mentioned tools (add plasTeX to the
list) into
the Wiki. Later I'll made separate announcement for this
wiki and
other resources - I want to prepare them first so any
further
discussions will went there.

FYI,
there's a discussion "How Do You Handle Your Enterprise
Documentation?"
on Slashdot:

"I'm curious as to what tools Slashdot readers use to
inventory and 
document their networks? What got me thinking about this is
the part 
VMWare has been taking in data centers. You've got your SAN,
various 
physical and logical networks, various VMs, and so forth. It
just adds a 
new layer of complexity in terms of documentation. I'm
curious as to what 
people have been using as for doing things like documenting
how their 
backups work, LAN settings, FW settings, where and what runs
what 
services, and so forth. How do you blueprint your entire IT
infrastructure 
so that someone brand new could start and figure out what
does what?"

=> http://ask.slashdot.org/article.pl?sid=06/12/15/0220210


  - Hubert