discuss: Linux documentation volunteer
Subject:
Re: [discuss] Linux documentation volunteer
From:
David Lawyer ####@####.####
Date:
5 Sep 2007 06:18:55 +0000
Message-Id: <20070905061743.GA2096@davespc>
On Mon, Sep 03, 2007 at 05:14:39PM -0700, Steven Meralevitz wrote:
> Dear Linux Documentation Project,
>
> I'm waddling my way through Fedora but need some assignments to help
> me learn the basics. Thus, I'd like to volunteer for the LInux
> Documentation Project,
>
> As to my background, I work in application support for an online
> trading firm in Chicago and have taught myself DHTML as well as
> various software packages. So I'm not afraid to roll up my sleeves
> and get dirty with software--I just need practice and I'm not sure
> how to get it on my own.
I'd like to suggest something that may be too big and complex for you
to tackle. And the skills you'll learn will be pretty specialized.
It's developing the LinuxDoc markup language which is something like
html. Markup languages like this enable one to write one doc in that
markup language which then converts to various other formats such as
html, pdf, and plain text.
Improving LinuxDoc is a lot more than just coming up with some new
tags since any changes must also be accompanied by software changes so
the the new tags convert properly to various other formats like
plain-text and html. And it's not just a simple matter of tag
mapping. For such conversion, various other programs and parsers are
utilized, so you don't have to start from scratch.
I think that the existing LinuxDoc markup is not used much because
people are not aware of it and how easy it is to use. But it needs
improvement. It would be nice if it could be improved to the extent
where it would be a good substitute for DocBook markup. Then it
might become the most popular markup language to use directly. More
people might use it than now directly write html since it's a lot
easier to create html this way for websites etc.
So what I'm proposing would be of much wider use than just for LDP
authors, many of which use DocBook. There's been a lot of debate in
the past at LDP on the merits on DocBook vs. LinuxDoc and a lot of
misunderstanding too, since some thought one could make DocBook as
simple as LinuxDoc by just using a small subset of tags. Not so,
since DocBook requires the use of nested tags while for LinuxDoc, one
may often omit both opening and closing tags and LinuxDoc is clever
enough to figure out where to put the missing tags but doesn't display
them to the user so that the LinuxDoc source looks nice.
The script that runs LinuxDoc is in perl which is something like
shell-scripting. And then there the DTDs (Data Type Definitions) for
SGML. Both html and linuxdoc are SGML which is much more powerful than
the XML that docbook currently uses.
See my mini howto: Howtos-with-LinuxDoc.
http://www.ibiblio.org/pub/Linux/docs/HOWTO/other-formats/html_single/Howtos-with-LinuxDoc.html
See also a comparison of the two markups at
www.lafn.org/~dave/linux/ld_vs_db.txt
An alternative to modifying scripts yourself would be to get someone
else to modify the code. The person at Debian who actually maintains
linuxdoc-tools (not the official maintainer) might be willing if you
ask him and propose the specific changes you want. There are a lot of
improvements needed such as making it easier to include images, and to
generate <meta> tags for html (which someone once did but it never
made it into the mainstream code).
So without the grandiose goal of replacing DocBook, there are still
some minor improvements that would help.
David Lawyer
