docbook: Thread: is the linuxdoc DTD deprecated for LDP?

Dear all,

Months ago, I roamed the LDP site, reading about how to submit documents
to the LDP.

I *thought* I remember reading that the Linuxdoc DTD has been deprecated
in favor of SGML/docbook and XML.

I tried finding a reference to this in the LDP Author Guide and the LDP
website.  Couldn't find it.

Am I simply not remembering this correctly, or is docbook and XML really
favored over LinuxDoc?

References would be appreciated if I'm remembering correctly.

Thanks!
Pete

-- 
GPG Fingerprint: B9F1 6CF3 47C4 7CD8 D33E  70A9 A3B9 1945 67EA 951D

On Sat, 2002-08-03 at 12:35, Peter Jay Salzman wrote:
> Months ago, I roamed the LDP site, reading about how to submit documents
> to the LDP.
> 
> I *thought* I remember reading that the Linuxdoc DTD has been deprecated
> in favor of SGML/docbook and XML.
> 
> I tried finding a reference to this in the LDP Author Guide and the LDP
> website.  Couldn't find it.

In section 2.5 of the Author's guide it mentions that when an author
submits their document, a member of the LDP will translate the text to
DocBook markup and that from there on the markup would be in DocBook. 
But please read on.
 
> Am I simply not remembering this correctly, or is docbook and XML really
> favored over LinuxDoc?
> 
> References would be appreciated if I'm remembering correctly.

If you were to have this discussion in the discuss mailing list, you would 
probably find out that there are lots of folks still using Linuxdoc markup
and there are still a great deal of documents that don't require the
complexity of DocBook.

Ideally I think the LDP would like to see the latest markup used for
documentation, particularly XML since it's so platform friendly.  

Do you need help with DocBook at all?  Let me know if I can be of
assistance!

-- 
Tabatha Persad
Web: www.merlinmonroe.com
Linux Documentation Project Editor (http://www.tldp.org)
Gnu Writing Movement Contributor (http://gwm.gnu.org)
Linux Counter Area Manager US:wa (http://counter.li.org)

Hi Tabatha,

I should've been more upfront with you.  :-)

I'm the author of the Debian Jigdo mini-HOWTO, and someone translated
the mini-HOWTO to German, which I submitted to the German HOWTO
coordinator.

The submission was flatly rejected for two reasons:

1. It uses "oe" instead of the German umlat (easily fixed).
2. It uses SGML/Docbook rather than the Linuxdoc DTD.  Apparently,
   German submissions are ONLY allowed in Linuxdoc.  Not Docbook.
   And not easily fixed.

The translator's job would be much easier if he could just take my
future revisions, cut and paste the changes I've made and do the
translation.  Requiring him translate the markup language seems to be a
big waste of his time.  Especially since Docbook is one of the accepted
markup languages for LDP.

I was going to make the case why the German coordinator should drop the
requirement of Linuxdoc.  I thought I remembered reading somewhere that
Docbook and XML are favored over Linuxdoc, and was going to use that
fact to help bolster my case why he should accept the Debian Jigdo
mini-HOWTO's German translation, after all the "oe"'s were changed to
umlats.

My girlfriend can do the umlat thing quickly, since she's fluent in
German.  But translating the markup language is a hardship for everyone
involved, and seems unreasonable.

What do you think?  I can use some advice here.

Thanks, Tabatha!

Pete


begin Tabatha Persad ####@####.#### 
> On Sat, 2002-08-03 at 12:35, Peter Jay Salzman wrote:
> > Months ago, I roamed the LDP site, reading about how to submit documents
> > to the LDP.
> > 
> > I *thought* I remember reading that the Linuxdoc DTD has been deprecated
> > in favor of SGML/docbook and XML.
> > 
> > I tried finding a reference to this in the LDP Author Guide and the LDP
> > website.  Couldn't find it.
> 
> In section 2.5 of the Author's guide it mentions that when an author
> submits their document, a member of the LDP will translate the text to
> DocBook markup and that from there on the markup would be in DocBook. 
> But please read on.
>  
> > Am I simply not remembering this correctly, or is docbook and XML really
> > favored over LinuxDoc?
> > 
> > References would be appreciated if I'm remembering correctly.
> 
> If you were to have this discussion in the discuss mailing list, you would 
> probably find out that there are lots of folks still using Linuxdoc markup
> and there are still a great deal of documents that don't require the
> complexity of DocBook.
> 
> Ideally I think the LDP would like to see the latest markup used for
> documentation, particularly XML since it's so platform friendly.  
> 
> Do you need help with DocBook at all?  Let me know if I can be of
> assistance!
> 
> -- 
> Tabatha Persad
> Web: www.merlinmonroe.com
> Linux Documentation Project Editor (http://www.tldp.org)
> Gnu Writing Movement Contributor (http://gwm.gnu.org)
> Linux Counter Area Manager US:wa (http://counter.li.org)
> 

-- 
Please don't put my email address in your Outlook addressbook.

GPG Fingerprint: B9F1 6CF3 47C4 7CD8 D33E  70A9 A3B9 1945 67EA 951D

Hi Peter,

I've copied David Merrill with your message regarding the requirement of
Linuxdoc over DocBook markup made by the German coordinator.

David is more familiar with the translation effort and may be able to
offer some clarity on the subject for you.

I know that the English LDP encourages DocBook markup, but perhaps there
is some reason we are unaware of.  Let's see what David says about it!

Thanks,
Tabatha


On Sat, 2002-08-03 at 13:54, Peter Jay Salzman wrote:
> Hi Tabatha,
> 
> I should've been more upfront with you.  :-)
> 
> I'm the author of the Debian Jigdo mini-HOWTO, and someone translated
> the mini-HOWTO to German, which I submitted to the German HOWTO
> coordinator.
> 
> The submission was flatly rejected for two reasons:
> 
> 1. It uses "oe" instead of the German umlat (easily fixed).
> 2. It uses SGML/Docbook rather than the Linuxdoc DTD.  Apparently,
>    German submissions are ONLY allowed in Linuxdoc.  Not Docbook.
>    And not easily fixed.
> 
> The translator's job would be much easier if he could just take my
> future revisions, cut and paste the changes I've made and do the
> translation.  Requiring him translate the markup language seems to be a
> big waste of his time.  Especially since Docbook is one of the accepted
> markup languages for LDP.
> 
> I was going to make the case why the German coordinator should drop the
> requirement of Linuxdoc.  I thought I remembered reading somewhere that
> Docbook and XML are favored over Linuxdoc, and was going to use that
> fact to help bolster my case why he should accept the Debian Jigdo
> mini-HOWTO's German translation, after all the "oe"'s were changed to
> umlats.
> 
> My girlfriend can do the umlat thing quickly, since she's fluent in
> German.  But translating the markup language is a hardship for everyone
> involved, and seems unreasonable.
> 
> What do you think?  I can use some advice here.
> 
> Thanks, Tabatha!
> 
> Pete
> 
> 
> begin Tabatha Persad ####@####.#### 
> > On Sat, 2002-08-03 at 12:35, Peter Jay Salzman wrote:
> > > Months ago, I roamed the LDP site, reading about how to submit documents
> > > to the LDP.
> > > 
> > > I *thought* I remember reading that the Linuxdoc DTD has been deprecated
> > > in favor of SGML/docbook and XML.
> > > 
> > > I tried finding a reference to this in the LDP Author Guide and the LDP
> > > website.  Couldn't find it.
> > 
> > In section 2.5 of the Author's guide it mentions that when an author
> > submits their document, a member of the LDP will translate the text to
> > DocBook markup and that from there on the markup would be in DocBook. 
> > But please read on.
> >  
> > > Am I simply not remembering this correctly, or is docbook and XML really
> > > favored over LinuxDoc?
> > > 
> > > References would be appreciated if I'm remembering correctly.
> > 
> > If you were to have this discussion in the discuss mailing list, you would 
> > probably find out that there are lots of folks still using Linuxdoc markup
> > and there are still a great deal of documents that don't require the
> > complexity of DocBook.
> > 
> > Ideally I think the LDP would like to see the latest markup used for
> > documentation, particularly XML since it's so platform friendly.  
> > 
> > Do you need help with DocBook at all?  Let me know if I can be of
> > assistance!

-- 
Tabatha Persad
Web: www.merlinmonroe.com
Linux Documentation Project Editor (http://www.tldp.org)
Gnu Writing Movement Contributor (http://gwm.gnu.org)
Linux Counter Area Manager US:wa (http://counter.li.org)

On Sat, 3 Aug 2002, Peter Jay Salzman wrote:

> 2. It uses SGML/Docbook rather than the Linuxdoc DTD.  Apparently,
>    German submissions are ONLY allowed in Linuxdoc.  Not Docbook.

This is inadmissible.  (IMHO, of course! :)
Linuxdoc SGML is _acceptable_ -- but should not be made mandatory -- for
any LDP document.  And of course, ASCII, Docbook SGML and Docbook XML
are equally acceptable.  None is mandatory.

> I was going to make the case why the German coordinator should drop the
> requirement of Linuxdoc.

Easy.  Linuxdoc doesn't allow for the incorporation of images.
(You could always be awkward, and deliberately include a screenshot into
your HOWTO.)

>  I thought I remembered reading somewhere that
> Docbook and XML are favored over Linuxdoc

This has often been expressed on the mailing list; maybe it's now time
to include it in the official documentation if people are going to get
unnecessarily awkward about mandating markup formats.

My tuppenn'orth.

msw
-- 

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Saturday 03 August 2002 10:33 am, Tabatha Persad wrote:
> Hi Peter,
>
> I've copied David Merrill with your message regarding the requirement
> of Linuxdoc over DocBook markup made by the German coordinator.
>
> David is more familiar with the translation effort and may be able to
> offer some clarity on the subject for you.
>
> I know that the English LDP encourages DocBook markup, but perhaps
> there is some reason we are unaware of.  Let's see what David says
> about it!

I don't know anything at all about the German LDP, sorry.

- -- 
David C. Merrill                         http://www.lupercalia.net
Linux Documentation Project                   ####@####.####
Lead Developer                                 http://www.tldp.org


O Seas of Caladan,
O people of Duke Leto --
Citadel of Leto Fallen
Fallen forever...
	-- from "Songs of Muad'Dib" by the Princess Irulan
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.7 (GNU/Linux)

iD8DBQE9TeCvWC4Sq/MWsY0RAgmuAKCVcoVCNB1rMNMc5JrXfHnMtyejngCeN9WO
G9KJ76T7VUW3FnIEkksGG5Y=
=feyB
-----END PGP SIGNATURE-----

On Sun, 2002-08-04 at 22:19, David Merrill wrote:
> On Saturday 03 August 2002 10:33 am, Tabatha Persad wrote:
> > Hi Peter,
> >
> > I've copied David Merrill with your message regarding the requirement
> > of Linuxdoc over DocBook markup made by the German coordinator.
> >
> > David is more familiar with the translation effort and may be able to
> > offer some clarity on the subject for you.
> >
> > I know that the English LDP encourages DocBook markup, but perhaps
> > there is some reason we are unaware of.  Let's see what David says
> > about it!
> 
> I don't know anything at all about the German LDP, sorry.

Ah, well it was worth a try.  It would be nice to understand why they
only accept LinuxDoc over DocBook, but I suppose someone will have to
step forth and explain those reasons.


-- 
Tabatha Persad
Web: www.merlinmonroe.com
Linux Documentation Project Editor (http://www.tldp.org)
Gnu Writing Movement Contributor (http://gwm.gnu.org)
Linux Counter Area Manager US:wa (http://counter.li.org)

Tabatha Persad wrote:
> [...] Ah, well it was worth a try.  It would be nice to understand
> why they only accept LinuxDoc over DocBook, but I suppose
> someone will have to step forth and explain those reasons.

Is there any 'official' relationship with Marco Budde,
####@####.#### the operator of the project?
Main page is http://www.tu-harburg.de/dlhp/

The general appearance seems to be typical for German
old-school, though. You should know that German netiquette
is many times more extreme than it ever was in it's originating
culture. (BTW: I'm Austrian, and we are not too fond of that
barrack yard style).

There is a document explaining whereabouts of the project
(similar to the Author Guide here). I translated interesting
parts:

# Die HOWTOs sollten inhaltlich korrekt sein. Insbesondere
# bei Übersetzungen von LDP HOWTOs sollte unbedingt vorher
# überprüft werden, ob die HOWTO es überhaupt wert ist,
# übersetzt zu werden. Leider gibt es beim LDP anscheinend
# keine Qualitätskontrolle, so daß viele LDP HOWTOs teilweise
# bis völlig falsch sind.

Content of HOWTOs should be correct. Before considering
translation of LDP HOWTOs you should absolutely verify
that the HOWTO is worth the trouble of translation at all.
Regrettably there does not seem to be quality control at LDP,
resulting in a lot of LDP HOWTOs being partially or completely wrong.

Later on it is declared that the project uses sgml-tools 1.0.9.
(absolutely no comment on other tools). Using version 2.x of
sgml-tools is not accepted because of incompatibilities and
bugs. The story continues with the revelation that recent
compilers fail to build the original sources of sgml-tools 1.0.9,
so the project provides a patch. But that's not the end:

# Hierbei sollte man jedoch unbedingt beachten, daß die LDP
# HOWTOs auf einer anderen Formatierungsrichtlinie beruhen.
# Man kann also nicht einfach die bestehende Formatierung
# übernehmen, sondern muß diese eventuell an die in diesem
# Dokument beschriebene anpassen. 

Take into account that LDP HOWTOs are based on a different
formatting guideline. You can't just take over the existing
format but possibly have to change it to the one described in
this document. And the only example on that page is 
<!doctype linuxdoc system>

Though this be madness, yet there is method in it.

The document links to the old site name, by the way: 
http://www.linuxdoc.org/docs.html#howto 
So I guess that Marco Budde has no close relationship to
this list or TLDP.

Can any of the 'politicians' please speak up?

-- 
GMX - Die Kommunikationsplattform im Internet.
http://www.gmx.net

hi alexander and all,

if i understand this correctly, we have a problem.

the last thing i wanted was to stir up controversy.  but by the same
token, i feel pretty awful that someone took the time to translate 15
pages of docbook and it's beginning to look like his effort will be
useless.

the translator doesn't even know docbook -- he just translates the
"stuff" that goes between the tags.  asking him to learn both docbook
and linuxdoc in order to translate both the words and the markup is just
too much to ask.  i would be embarrased to even ask that of him.

it's also not fair to german speaking people who'd rather learn about
debian jigdo in their own language.

i'm a nobody here -- just a writer who has a guide, howto and a
mini-howto under his belt.   can someone with clout plead the case that
the standards for tldp should be ...  standard?

or is there someway of short circuiting marco and submitting the german
document directly to tldp?

pete



begin Alexander Bartolich ####@####.#### 
> Tabatha Persad wrote:
> > [...] Ah, well it was worth a try.  It would be nice to understand
> > why they only accept LinuxDoc over DocBook, but I suppose
> > someone will have to step forth and explain those reasons.
> 
> Is there any 'official' relationship with Marco Budde,
> ####@####.#### the operator of the project?
> Main page is http://www.tu-harburg.de/dlhp/
> 
> The general appearance seems to be typical for German
> old-school, though. You should know that German netiquette
> is many times more extreme than it ever was in it's originating
> culture. (BTW: I'm Austrian, and we are not too fond of that
> barrack yard style).
> 
> There is a document explaining whereabouts of the project
> (similar to the Author Guide here). I translated interesting
> parts:
> 
> # Die HOWTOs sollten inhaltlich korrekt sein. Insbesondere
> # bei ?bersetzungen von LDP HOWTOs sollte unbedingt vorher
> # ?berpr?ft werden, ob die HOWTO es ?berhaupt wert ist,
> # ?bersetzt zu werden. Leider gibt es beim LDP anscheinend
> # keine Qualit?tskontrolle, so da? viele LDP HOWTOs teilweise
> # bis v?llig falsch sind.
> 
> Content of HOWTOs should be correct. Before considering
> translation of LDP HOWTOs you should absolutely verify
> that the HOWTO is worth the trouble of translation at all.
> Regrettably there does not seem to be quality control at LDP,
> resulting in a lot of LDP HOWTOs being partially or completely wrong.
> 
> Later on it is declared that the project uses sgml-tools 1.0.9.
> (absolutely no comment on other tools). Using version 2.x of
> sgml-tools is not accepted because of incompatibilities and
> bugs. The story continues with the revelation that recent
> compilers fail to build the original sources of sgml-tools 1.0.9,
> so the project provides a patch. But that's not the end:
> 
> # Hierbei sollte man jedoch unbedingt beachten, da? die LDP
> # HOWTOs auf einer anderen Formatierungsrichtlinie beruhen.
> # Man kann also nicht einfach die bestehende Formatierung
> # ?bernehmen, sondern mu? diese eventuell an die in diesem
> # Dokument beschriebene anpassen. 
> 
> Take into account that LDP HOWTOs are based on a different
> formatting guideline. You can't just take over the existing
> format but possibly have to change it to the one described in
> this document. And the only example on that page is 
> <!doctype linuxdoc system>
> 
> Though this be madness, yet there is method in it.
> 
> The document links to the old site name, by the way: 
> http://www.linuxdoc.org/docs.html#howto 
> So I guess that Marco Budde has no close relationship to
> this list or TLDP.
> 
> Can any of the 'politicians' please speak up?
> 
> -- 
> GMX - Die Kommunikationsplattform im Internet.
> http://www.gmx.net

On Mon, 2002-08-05 at 03:55, Alexander Bartolich wrote:
> There is a document explaining whereabouts of the project
> (similar to the Author Guide here). I translated interesting
> parts:
> 
> # Die HOWTOs sollten inhaltlich korrekt sein. Insbesondere
> # bei Übersetzungen von LDP HOWTOs sollte unbedingt vorher
> # überprüft werden, ob die HOWTO es überhaupt wert ist,
> # übersetzt zu werden. Leider gibt es beim LDP anscheinend
> # keine Qualitätskontrolle, so daß viele LDP HOWTOs teilweise
> # bis völlig falsch sind.
> 
> Content of HOWTOs should be correct. Before considering
> translation of LDP HOWTOs you should absolutely verify
> that the HOWTO is worth the trouble of translation at all.
> Regrettably there does not seem to be quality control at LDP,
> resulting in a lot of LDP HOWTOs being partially or completely wrong.

Actually, there is a group of 30 volunteers working diligently to
address the format and content of new and existing documentation, with
new usually given priority over existing.  In addition, though LinuxDoc
is still a very popular format, there is enough evidence that supports
DocBook, (XML in particular) to be considered most current flavor of
markup, and the most portable. The documentation and regular updates are
always in CVS, and readily available for check-out.

The use of Linuxdoc over DocBook is subjective, and I think there may be
plenty of reasons to continue using LinuxDoc, but I don't understand at
all why DocBook would be declined. Graphics support comes to mind.

> Take into account that LDP HOWTOs are based on a different
> formatting guideline. You can't just take over the existing
> format but possibly have to change it to the one described in
> this document. And the only example on that page is 
> <!doctype linuxdoc system>
> 
> Though this be madness, yet there is method in it.
> 
> The document links to the old site name, by the way: 
> http://www.linuxdoc.org/docs.html#howto 
> So I guess that Marco Budde has no close relationship to
> this list or TLDP.

I think it's great to have the LDP represented, but maybe more
correlation to the main site should be considered.  Are all the
documents at that site in Linuxdoc?  Surely there is a combination of
people familiar with the tools to be able to verify docbook in German? 
If not, then maybe there is a gap that needs to be fulfilled.  Why not
take this opportunity to bring things up to date?  

> Can any of the 'politicians' please speak up?

That would be fantastic!

As for the document that started this discussion, I think the author
keep it ready.  David Merrill's Lampadas system for the LDP should be
able to use this DocBook source for users accessing that language. 


-- 
Tabatha Persad
Web: www.merlinmonroe.com
Linux Documentation Project Editor (http://www.tldp.org)
Gnu Writing Movement Contributor (http://gwm.gnu.org)
Linux Counter Area Manager US:wa (http://counter.li.org)