Subject:
Re: LinuxDoc vs. DocBook (was Re: Staff Election)
From:
Binh Nguyen ####@####.####
Date:
2 Apr 2005 07:08:59 -0000
Message-Id: <1081abc905040123089a1cd8d@mail.gmail.com>
Why is it that this conversation always brings the worst out in people?
I never insulted anyone....
****
You're arguing semantics....
theory - 1) set of reasoned ideas intended to explain facts or events
2) opinion or supposition, not necessarily based on reasoning
3) ideas or suppositions in general (contrasted with practice)
4) (statement of the) principles on which a subject is based
hypothesis - idea or suggestion that is based on known facts that is used
a basis for reasoning or further analysis
Source: Oxford Advanced Learner's Dictionary
Even if you believe that I haven't quite fitted into 1), 3), or 4) then I
clearly would have made a fist of 2) :)
****
****
The reason why I proposed the legal advisor position in the first place was
due to the very issue of licensing and copyright issues. We will not make
any progress until we gain someone who is trained in legal issues which
leads me to the issue of advertising for more volunteers once our 'restructure'
is complete. ie. proper job descriptions and allocations of people to them,
etc....
****
****
How do you avoid this conversation when David brings up LinuxDoc in such a
significant number of his emails.
A search via Google for
"david lawyer site:lists.tldp.org" returned 640 hits
"david lawyer linuxdoc site:lists.tldp.org" returned 857 hits
"david lawyer docbook site:lists.tldp.org" returned 575 hits
Clearly, something strange is occuring here!
Further, I draw you to
http://lists.tldp.org/index.cgi?1:mss:6659:200402:aoajnioenajphdefnbnn
David stated
#### Start Quote
I didn't say it was a "waste of time" ( reading the LDP-Author-Guide)
for someone to read. But I
thought it was a waste of time for me to read since I didn't care to
learn a lot about DocBook, etc. However, I've recently been reading
some stuff about DocBook (Raymond's HOWTO, etc.) so I can better
criticize it.
#### End Quote
He is clearly biased and no doubt I am as well. However, it is also clear
that I do not post the advantages of using Docbook everytime I make a
post to this list.
****
****
For Guides, 1 LinuxDoc, 25 DocBook.
For HOWTOs, 1 WikiText, 243 LinuxDoc, 283 DocBook.
283+25/1+283+243
308/527
58.44% of our repository is Docbook....
****
****
My proposal is not to move the entire repository to DocBook. All people who
currently use LinuxDoc can continue to use it. However, all new documents
should be written in Docbook. If you have been following the latest incarnation
of this conversation then you would have noticed the issues that have been
raised such as metadata, tool availability, the popularity of Docbook and
the like.... Limiting the choice of format also reduces the amount of
pre-reading about
LinuxDoc Vs DocBook which is required before deciding which format to use.
Further, the 'LDP-Author-Guide' states that
'The LDP uses a markup language known as DocBook.' yet about a page on
it goes on to state :-
#### Start Quote
5.4. Markup Languages Accepted by TLDP
The LDP stores its documents in the following markup languages:
1. DocBook XML version 4.2 (preferred), 4.1.2
2. DocBook SGML version 4.2, 4.1, or 3.x
3. LinuxDoc SGML
#### End Quote
Clearly, these statements are ambiguous.
****
****
It was stated :-
http://lists.tldp.org/index.cgi?1:man:5966:200312:claiepedajakajhoajgg
#### Start Quote
LinuxDoc merits:
1. A lot less time to learn
2. Much easier to type (shorter and fewer tags)
3. Easier to read (for example, no tags for paragraphs)
4. Less problems with the software
#### End Quote
and
#### Start Quote
Ahh, that is an incorrect assumption. It certainly makes it
easier for *us* to publish one format, but for authors,
limiting the choices of format can add (sometimes a lot of)
extra time to the document writing cycle.
### End Quote
I admit that learning DocBook was never easy but so is learning
LinuxDoc for the LDP only to learn that most other major projects use DocBook.
I don't know about you but I would find this to be a severe turn off
for continuing input to other documentation projects. As such, I believe
that it would be in the author's best interest to learn something that they
can also utilise elsewhere. Short term pain for long term gain.
Once again to put into stark reality the popularity of Docbook against
LinuxDoc a search for the keywords 'linuxdoc' and 'docbook' on Google returned
512,000 and 1,480,000 respectively.
Moreover, a search for the terms on Google for the keywords
"linuxdoc gui wysiwyg" returned 806 hits while
"docbook gui wysiwyg" returned 18300 hits.
Further, in David Lawyer's 'Howtos-with-LinuxDoc',
http://www.ibiblio.org/pub/Linux/docs/HOWTO/Howtos-with-LinuxDoc
document it is stated,
'the number of people who use DocBook greatly exceeds the number
using LinuxDoc.'
and 'The LDP also automatically converts a LinuxDoc HOWTO to DocBook
after you submit it.'
I'm not sure how many authors are 'one-hit wonders' but I'd assume
that they are greater in number than multi-document authors. By forcing
people to use DocBook we are no longer in the situation of having to adhere to
this statement.... not that we do, judging by our repository.
In the case of the smaller HOWTOs I am willing to convert the documents
over to DocBook by myself (if need be).
Earlier in this conversation it was stated :-
'For paragraph separation it uses infinitely more tags.'
This is clearly untrue. Infinite implies limitless/boundless. This argument
is biased and should be stricken from the record.
To quote EJH, 'For F***'s Sake' even ESR, a former LinuxDoc developer
said, 'I say kill it now. DocBook is better.'
As Greg most recently stated automated conversion from LinuxDoc to DocBook
(I'm not sure about DocBook to LinuxDoc) isn't without its flaws. As such,
it would either require further development of the LinuxDoc to DocBook
tools or manual
editing. Neither is plausible given our current state of lack of volunteers
(damn it, let's advertise), hence my current belief for our usage of
only one format.
Once again to put into stark reality the lack of tools for LinuxDoc is yet
another Google search of :-
"linuxdoc to docbook" conversion returned 679 hits
"docbook to linuxdoc" conversion 73 returned hits
Anybody know what converting HTML to DocBook instead of from LinuxDoc
to DocBook is like?
I believe that the primary reason why DocBook is perceived to be so
difficult to learn/use
is that the documentation written for it is so long. Further, it
doesn't help when the
templates aren't properly linked (See Section A.1 Book Templates of
the LDP-Author-Guide).
If it were made glaringly obvious to new authors to use these
templates instead of marking
up documents themselves I believe that the issue of Docbook difficulty
would be redundant.
Moreover, the LDP has a history of using LinuxDoc. Maintaining the
status quo would be
far easier than moving entirely to a 'new' format.
If you'd like to argue in terms of reasoning and logic then an argument
is only valid if its premises are true (http://www.answers.com/topic/valid).
Hence, in order to lay the foundations for an LDP with a better future
and one that
has relevance in the prevailing Open Source world I believe that it
will be necessary
for us to utilise technologies that have been established as the
'standard' as they
will be the technologies for which new tools and innovations will be
created for.
****
Regards,
Binh.
