Re: Docbook tools

Re: Docbook tools

[Stephane Bortzmeyer]

On Monday 6 September 1999, at 10 h 26, the keyboard of Guy Brand 
<guybrand@chimie.u-strasbg.fr> wrote:

>   I was wondering last week why there wasn't a generic DocBook mailing
>   list where specific questions to the DTD, usage, etc could be sent.

davenport@berkshire.net

AFAIK, it is only about the DTD (the last thread was about extensions to 
DocBook to document object-oriented languages), not about add-ons like the 
stylesheets, and even less about the tools like jade or SGMLtools.

Re: Docbook tools

[Mark Galassi]

    Stephane> On Monday 6 September 1999, at 10 h 26, the keyboard of
    Stephane> Guy Brand <guybrand@chimie.u-strasbg.fr> wrote:

    >> I was wondering last week why there wasn't a generic DocBook
    >> mailing list where specific questions to the DTD, usage, etc
    >> could be sent.

    Stephane> davenport@berkshire.net

    Stephane> AFAIK, it is only about the DTD (the last thread was
    Stephane> about extensions to DocBook to document object-oriented
    Stephane> languages), not about add-ons like the stylesheets, and
    Stephane> even less about the tools like jade or SGMLtools.

That's right, but there are other lists too:

dssslist@mulberrytech.com (how to write stylesheets)

sgml-tools@via.ecp.fr (pretty much anything related to tools)

You mention "the DTD and usage", so I would try the davenport list.
It's low enough volume, and easy to filter.

DocBook tools

[Clarissa Kao]

Hi.

I got a copy of Mark Galassi's "Get Going With DocBook" guide. Appendix
A.2 seems to indicate that there is a version of the DocBook tools
available for windows users. However, it doesn't say where we can get
the tools.

Thanks,
Clarissa
________________________________
Clarissa S. Kao
ckao@virage.com
(650)581-8025

Re: DocBook tools

[Mark Galassi]

Unfortunately the Windows packages were never maintained.  But the
good news for you is that both Jade and the modular stylesheets come
pre-packaged for Windows, so you don't have to do a difficult build
process.

Re: Docbook tools

[David C. Mason]

Eric Bischoff <ebisch@cybercable.tm.fr> writes:

> - It is indeed a very good idea to use RPM packages for those using
> RedHat-based
> systems (I am one, I am using LinuxPPC for Macintosh ;-) ). What is
> the reason
> for putting both the 3.0 version and the 3.1 version of the DocBook
> DTD in
> the RPM archive? It makes the file bigger.
> 

It is unfair to compare a system like RPM to tar.gz or other
archiving/compression formats. RPMs *add* functionality, thus
sometimes larger files. Mark is working on other packages.


> - Have you encountered the same problems we have encountered with
> non-English
> languages and the TeX backend ? We did not manage to make the Babel
> package
> work with French, and we still feel very unsecure about Corean,
> Chinese (all
> encodings), Greek and Russian. We also would love to switch to
> Unicode encoding
> for all non-latin languages. Have you already any experience about
> that ? 
> 

This is actually a problem with TeX itself. The French style file
(french.sty) now has some major licensing issues thanks to its creator
changing the license. The file was removed from the CTAN repository
and it breaks things like jadetex that still try to call it. This
should be fixed in Mark's latest version but you might find older
versions still rely on the style file. 

As you might guess, this is bad news for anyone who wants to write
French documents and use TeX but as long as they want to agree to the
new license they can still use it. I would recommend French users to
make html with a big juicy note as to why there is no PostScript or
TeX files.

As to the CKVJ languages, there is now support for Japanese in DocBook
but you will need to write language files for other languages. These
files are part of the Stylesheets and are really quite easy to write
as long as you have someone who knows the language. TeX should be able
to handle the CKVJ languages fine, I don't know about Greek. Russian
works fine but make sure you have the latest stylesheets as there is a
new ISOcryl(or whatever its called) file in there. Norman Walsh can
speak to this a little better than me.
 
Good Luck, its great to see you guys moving to DocBook, this is a
great step for your project and mine(GNOME) to start sharing things
like a help browser backend.

Cheers,

Dave

Re: Docbook tools

[Eric Bischoff]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 2232 bytes --]

David,

Thanks for your kind answer.

Le Mon, 06 Sep 1999, David C. Mason a écrit :
> Eric Bischoff <ebisch@cybercable.tm.fr> writes:
> > What is the reason
> > for putting both the 3.0 version and the 3.1 version of the DocBook
> > DTD in the RPM archive? It makes the file bigger.
> 
> It is unfair to compare a system like RPM to tar.gz or other
> archiving/compression formats. RPMs *add* functionality, thus
> sometimes larger files. Mark is working on other packages.

Maybe you misunderstood me. I was wondering why putting both the 3.0 and the 3.1
versions in the same RPM. Why not only the 3.1 version ? I was in no way
comparing RPMs to tarballs. I should have said "RPM packages" and not "RPM
archives".

> This is actually a problem with TeX itself. The French style file
> (french.sty) now has some major licensing issues thanks to its creator
> changing the license. The file was removed from the CTAN repository
> and it breaks things like jadetex that still try to call it. This
> should be fixed in Mark's latest version but you might find older
> versions still rely on the style file. 

Thanks for the info.

> As to the CKVJ languages, there is now support for Japanese in DocBook
> but you will need to write language files for other languages. These
> files are part of the Stylesheets and are really quite easy to write
> as long as you have someone who knows the language.

We have such people at KDE. Errr... what does CKVJ stand for ?

> Good Luck, its great to see you guys moving to DocBook, this is a
> great step for your project and mine(GNOME) to start sharing things
> like a help browser backend.

I fully support the policy of making KDE and GNOME as much compatible as we
can, I am very happy to meet you on this mailing list, and I hope we will have
the occasion to help one another many times again. The BIG conversion from
linuxdoc to docbook at KDE is to take place in very short time now.

Greetings,

Eric
--
 __________________________________________________
     .~.    "Release of Windows 2000 has been
     /V\      postponed until January 1, 1901"
   //   \\
  /(     )\ 
    ^^-^^
 __________________________________________________
Eric Bischoff - mailto:ebisch@cybercable.tm.fr

Re: Docbook tools

[David C. Mason]

Eric Bischoff <ebisch@cybercable.tm.fr> writes:


> > It is unfair to compare a system like RPM to tar.gz or other
> > archiving/compression formats. RPMs *add* functionality, thus
> > sometimes larger files. Mark is working on other packages.
> 
> Maybe you misunderstood me. I was wondering why putting both the 3.0 and the 3.1
> versions in the same RPM. Why not only the 3.1 version ? I was in no way
> comparing RPMs to tarballs. I should have said "RPM packages" and not "RPM
> archives".

I most definitely did misunderstand you. I can try to blame it on my
illness over the weekend or I can just apologize... sorry.


> > As to the CKVJ languages, there is now support for Japanese in DocBook
> > but you will need to write language files for other languages. These
> > files are part of the Stylesheets and are really quite easy to write
> > as long as you have someone who knows the language.
> 
> We have such people at KDE. Errr... what does CKVJ stand for ?

Mark is right.. Chinese, Korean, Vietnamese, and Japanese. For your
information, this is how Asian languages have been referred to over the
years in the world of i18n. In fact, there is a very *complete* book
put out by O'Reilly about i18n called CKVJ that you can recommend to
anyone who is doing work on unicode support et al.


> 
> > Good Luck, its great to see you guys moving to DocBook, this is a
> > great step for your project and mine(GNOME) to start sharing things
> > like a help browser backend.
> 
> I fully support the policy of making KDE and GNOME as much compatible as we
> can, I am very happy to meet you on this mailing list, and I hope we will have
> the occasion to help one another many times again. The BIG conversion from
> linuxdoc to docbook at KDE is to take place in very short time now.
> 

Well I hope we can make the two desktops as compatible as possible,
but if not, we can at least keep the documentation side together. Just
for your information I took a look at the new KDE help browser and
there are many things I like about it. We are close to embarking on
our own *real* effort at a help browser with two key
features...hopefully these projects can share some attributes.

The two key features of our help browser will most likely be [a]
Mozilla based display. This is why we have no real help browser, we
want to use the Mozilla Gecko engine to display the content..so we
wait. [b]We are now leaning toward using XML instead of html for the
online content. That way we can build feature rich searching and
indexing based on content. We will keep the ability to view html based
help but we really want to explore the possibilities of content based
searching the way it was always meant to be.

Some things to think about.


Cheers,

Dave


-- 

          David Mason
        Red Hat AD Labs

        dcm@redhat.com

Re: Docbook tools

[Eric Bischoff]

> Well I hope we can make the two desktops as compatible as possible,
> but if not, we can at least keep the documentation side together. Just
> for your information I took a look at the new KDE help browser and
> there are many things I like about it. We are close to embarking on
> our own *real* effort at a help browser with two key
> features...hopefully these projects can share some attributes.

I like the KDE help browser too. What I like most is that it makes the man
pages available with just one click of mouse ;-)

> The two key features of our help browser will most likely be [a]
> Mozilla based display. This is why we have no real help browser, we
> want to use the Mozilla Gecko engine to display the content..so we
> wait. [b]We are now leaning toward using XML instead of html for the
> online content. That way we can build feature rich searching and
> indexing based on content. We will keep the ability to view html based
> help but we really want to explore the possibilities of content based
> searching the way it was always meant to be.
> 
> Some things to think about.

Sure. The Linux Documentation Project planned to move to XML-DocBook. How far
are they ?

Eric
--
 __________________________________________________
     .~.    "Release of Windows 2000 has been
     /V\      postponed until January 1, 1901"
   //   \\
  /(     )\ 
    ^^-^^
 __________________________________________________
Eric Bischoff - mailto:ebisch@cybercable.tm.fr

Re: Docbook tools

[David C. Mason]

Eric Bischoff <ebisch@cybercable.tm.fr> writes:

> 
> I like the KDE help browser too. What I like most is that it makes the man
> pages available with just one click of mouse ;-)


Yes indeed. The one thing I don't like about it is that it seems to
use some "specialized" html tags to do the navigation et al. I am very
much against adding tags for one project... we've had way too much of
that in the markup language world. I could be wrong about this but
that is what I gathered from a quick look.


> Sure. The Linux Documentation Project planned to move to XML-DocBook. How far
> are they ?


I don't *ever* make predictions on things getting done with
LDP. Considering no body knows who is in charge... maybe never.


Cheers,

Dave

-- 

          David Mason
        Red Hat AD Labs

        dcm@redhat.com

Re: Docbook tools

[Edward C. Bailey]

>>>>> "Dave" == David C Mason <dcm@redhat.com> writes:

Dave> Eric Bischoff <ebisch@cybercable.tm.fr> writes:
...
>> Sure. The Linux Documentation Project planned to move to
>> XML-DocBook. How far are they ?

Dave> I don't *ever* make predictions on things getting done with
Dave> LDP. Considering no body knows who is in charge... maybe never.

I'd have to agree, sorry to say; I lurk on the LDP list, and at most all
that is ever discussed is SGML-DocBook, and as soon as the subject is
broached someone else always chimes in about how we should stick with
Linuxdoc, DocBook is too hard to learn, yadda, yadda, yadda.  And then the
subject is dropped. It's pretty sad...

Ed_who's_in_the_midst_of_a_big_DocBook_conversion_and_isn't_very_sympathetic!
:-)
-- 
Ed Bailey        Red Hat, Inc.          http://www.redhat.com/

Docbook tools

[Eric Bischoff]

Hello everybody,

My name is Eric Bischoff and I recently subscribed to docbook-tools-discuss at
Cygnus. I am participating to the KDE project as documentation coordinator. KDE
is an integrated desktop for Unix systems and has several links with the Linux
project and other free software initiatives. Visit http://www.kde.org for more
information.

We at KDE are in the process of changing our documentation file format from
LinuxDoc-SGML to DocBook-SGML. In order to make it easy for our many translators
and documentation writers to use DocBook tools such as James Clark's Jade, the
OASIS DocBook DTD and Norman Walsh Stylesheet, I was planning to package all
this stuff all together - exactly what you have done at Cygnus.

So it is very likely that such an effort should not be duplicate, and that we
should use Cygnus tools here at KDE, maybe with some extensions and/or
parametrization for the specific needs of the KDE project.

The DocBook team at KDE has also developped some tools that could prove of some
interest for other users, such as a crash course to DocBook that people report
to be of quality. Have a look at
http://www.kde.org/documentation/docbook/index.html .

I had not the time to examine the details of Cygnus packaging, this will be
done in the next days. But a few questions I would love to ask have already
arisen :

- You have packaged nearly exactly the same tools I was planning to, with the
same version numbers. There is one main exception, Norman Walsh's stylesheet. I
may be wrong, but it looks like you have packaged version 0.10, whereas version
1.42 is the current one. Is there a reason for that ?

- Why not putting everything in a single tarball / RPM / SRPM ? There could be
a single ./configure / make / make install sequence.

- It is indeed a very good idea to use RPM packages for those using RedHat-based
systems (I am one, I am using LinuxPPC for Macintosh ;-) ). What is the reason
for putting both the 3.0 version and the 3.1 version of the DocBook DTD in
the RPM archive? It makes the file bigger.

- Have you encountered the same problems we have encountered with non-English
languages and the TeX backend ? We did not manage to make the Babel package
work with French, and we still feel very unsecure about Corean, Chinese (all
encodings), Greek and Russian. We also would love to switch to Unicode encoding
for all non-latin languages. Have you already any experience about that ? 

- I don't know what the hyperref package is and why it may be part of DocBook
tools. Maybe I should try harder to understand that. Any help ?

I hope that all these questions are interesting this discussion list, I
apologize in advance for not having read all the archive of this mailing list,
I was short in time.

Eric

PS I will forward the reply(ies) to the KDE DocBook team : Frederik Fouvry and
David Rugge.
--
 __________________________________________________
     .~.    "Release of Windows 2000 has been
     /V\      postponed until January 1, 1901"
   //   \\
  /(     )\ 
    ^^-^^
 __________________________________________________
Eric Bischoff - mailto:ebisch@cybercable.tm.fr

Re: Docbook tools

[Guy Brand]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 2887 bytes --]

Le 05 Septembre vers 21:30, Eric Bischoff écrivait :

> Hello everybody,

  Salut Eric wie gets :))

> I was planning to package all
> this stuff all together - exactly what you have done at Cygnus.

  Yes, thanks to Mark Galassi who perfectly reached his aim : providing
  Linux RedHat (alike) users with a simple "kit" to produce DocBook. 
  I was about to package all the stuff for Debian, when Adam Di Carlo
  informed me that he already did the job. Seems that we have enough 
  tools to produce docbookies. What lacks is documentation on 
  producing docbooks and tweaking them to fit "personnal" needs.

> interest for other users, such as a crash course to DocBook that people report
> to be of quality. Have a look at
> http://www.kde.org/documentation/docbook/index.html .

  This course does not contain more information one could already find
  in Mark Galassi's "Getting going with DocBook" or FreeBSD's quick doc
  on using DocBook in the FreeBSD documentation project. We still need a
  good guide, complete and with many examples, not just the basic one of
  course. I'm not criticizing what you did at KDE, and as we know each
  other, Eric, I think you understand perfectly what I mean. Obvisouly a
  DocBook-HOWTO is needed in the LDP.

> There is one main exception, Norman Walsh's stylesheet. I
> may be wrong, but it looks like you have packaged version 0.10, whereas version
> 1.42 is the current one. Is there a reason for that ?

  Mark will explains himself :)

> - Why not putting everything in a single tarball / RPM / SRPM ? There could be
> a single ./configure / make / make install sequence.

  The RPMs are available with SPECs too, so you can rebuild them from
  scratch if needed. Also, the "docware kit" (Mark can I still call it
  that way ?) does include several products (jade, jadetex, etc.) which
  are separated projects... one just need them to have the whole
  stuff working, but why would one want such a big package ? Under
  Debian you just need the cygnus-stylesheets, jade, jadetex, docbook,
  etc are available as separated packages too. Don't forget there're many
  ways of using/producing valid DocBook docs :) It's true that under
  RedHat one need to have Mark's work to produce DocBook. I
  recently switched to a Debian box where several approaches are
  equivalently productive.

> for putting both the 3.0 version and the 3.1 version of the DocBook DTD in
> the RPM archive? It makes the file bigger.

  Modularity ? :)
  Probably the same answer as "why would one produce HTML docs conform
  to DTD version 3.2 and 4.0 ?"

> PS I will forward the reply(ies) to the KDE DocBook team

  I was wondering last week why there wasn't a generic DocBook mailing
  list where specific questions to the DTD, usage, etc could be sent.
  Of course there's still comp.text.sgml :)

  BuG

  PS : copies to S.Bortzmeyer and A. di Carlo
  

Re: Docbook tools

[Mark Galassi]

Dear Eric,

Others on this list have already answered some of your points, but let
me also mention a couple of things.  First some specific answers, and
some general comments at the bottom.

    Eric> I am participating to the KDE project as documentation
    Eric> coordinator. [...]

    Eric> We at KDE are in the process of changing our documentation
    Eric> file format from LinuxDoc-SGML to DocBook-SGML.

I am delighted that KDE will also be using DocBook.

    Eric> In order to make it easy for our many translators and
    Eric> documentation writers to use DocBook tools such as James
    Eric> Clark's Jade, the OASIS DocBook DTD and Norman Walsh
    Eric> Stylesheet, I was planning to package all this stuff all
    Eric> together - exactly what you have done at Cygnus.

    Eric> So it is very likely that such an effort should not be
    Eric> duplicate, and that we should use Cygnus tools here at KDE,
    Eric> maybe with some extensions and/or parametrization for the
    Eric> specific needs of the KDE project.

That is good thinking.

    Eric> The DocBook team at KDE has also developped some tools that
    Eric> could prove of some interest for other users, such as a
    Eric> crash course to DocBook that people report to be of
    Eric> quality. Have a look at
    Eric> http://www.kde.org/documentation/docbook/index.html .

This seems to overlap a lot with my tutorial, as others have already
mentioned.  Nik's FreeBSD DocBook tutorial (which started out with
mine) also overlaps.  Some day...

    Eric> I had not the time to examine the details of Cygnus
    Eric> packaging, this will be done in the next days. But a few
    Eric> questions I would love to ask have already arisen :

    Eric> - You have packaged nearly exactly the same tools I was
    Eric> planning to, with the same version numbers. There is one
    Eric> main exception, Norman Walsh's stylesheet. I may be wrong,
    Eric> but it looks like you have packaged version 0.10, whereas
    Eric> version 1.42 is the current one. Is there a reason for that
    Eric> ?

The version numbering is because I used to ship three alternative
DocBook stylesheets, of which Norm's was just one.  Nowadays I still
ship them, but I doubt they would work without a lot of work, so I
should eventually make the version number match Norm's.  My 0.10
tracks Norm's version 1.44.

    Eric> - Why not putting everything in a single tarball / RPM /
    Eric> SRPM ? There could be a single ./configure / make / make
    Eric> install sequence.

The packages are maintained separately, and they use different
approaches to building and installing.  Maintaining a proper GNU
build/install system for each of them would be hard.

The SGMLTools team tries to do this, and in my opinion they have not
pulled it off well: people have a terrible time installing SGMLTools
from source, although I think the blame is partly in their clever (but
maybe too clever) configuration system.

I do think this can be done, but it will take some real work:

1. coordinate with *all* the individual maintainers so that when they
   are ready to put a new version out, we provide them with the
   automake/autoconf stuff for GNU users.

2. work out exactly how a good automake/autoconf system works for
   emacs lisp (both emacs and xemacs) and TeX

3. clean up the underlying sgml-common module, and have a clear
   concept of how the various DTDs and catalog entries accumulate as
   you do a "make install" for each.

I would still maintain them as separate packages, but I would then
feel better about releasing tarballs too (not just RPMs).  The
packages are all very different, and they can work with other goals,
so I do not see any reason to combine them.

    Eric> - It is indeed a very good idea to use RPM packages for
    Eric> those using RedHat-based systems (I am one, I am using
    Eric> LinuxPPC for Macintosh ;-) ). What is the reason for putting
    Eric> both the 3.0 version and the 3.1 version of the DocBook DTD
    Eric> in the RPM archive? It makes the file bigger.

The reason is so that you can process both 3.0 and 3.1 DocBook
documents.  If you look at the mailing list archives, my most recent
large announcement talked about that in a bit more detail.

    Eric> - Have you encountered the same problems we have encountered
    Eric> with non-English languages and the TeX backend ? [...]

Dave Mason has already answered this point.  I will add that CKVJ (or
whatever the order was) probably stands for Chinese, Korean,
Vietnamese, Japanese.

    Eric> - I don't know what the hyperref package is and why it may
    Eric> be part of DocBook tools. Maybe I should try harder to
    Eric> understand that. Any help ?

No *immediate* help, except that jadetex uses it, and it used to not
come with a basic TeX distribution.  It does now, but I'm not sure
about the version numbers.  Next time I put out a package, I will see
if I can do without the hyperref stuff :-)

    Eric> I hope that all these questions are interesting this
    Eric> discussion list, I apologize in advance for not having read
    Eric> all the archive of this mailing list, I was short in time.

The questions are certainly quite intersting.  Thanks for
participating!

Let me now make a couple of suggestions:

* I strongly recommend that you use the same RPM distribution of tools
  that we use (I'm also trying to get the Debian guys to start working
  from common source).  You should participate in the software effort
  (it's not hard) so that we can come up with a whole collection of
  customizations for the stylesheets.  Ideally there should be the
  Cygnus customization (which is rather small), the GNOME one, the KDE
  one, the FreeBSD one, the "linux documentation project" one, and so
  forth.  I would like them all to be easy switches to "db2html" and
  the other "db2*" scripts.  I'll talk about this more some other
  time, when I outline my ideas for future enhancements.

* I would merge the tutorials together.  Take a look at mine
  ( http://nis-www.lanl.gov/~rosalia/docbook-intro.html ) and let me
  know if we can merge some of your beef with mine, and then maybe
  make a KDE-specific appendix.

* I am delighted about the possibility of KDE/GNOME cooperation in
  documentation issues.  We should talk about some aspects of this,
  like directory layout, help-topics locations, common Makefile.am
  documentaiton target rules, and maybe equivalent help menus.  We'd
  teach the other parts of the GNOME and KDE teams how well we work
  together on common standards.  And then we can also teach the
  Russians and the Chinese to live happily together.

Re: Docbook tools

[Rahul Dave]

Maybe the "canonical docbook RPMS should include the KDE customization
layer(which IMO does a aesthetically nicer job than Norm's defaults, for
admonitions at the very least), or cygnus-both.dsl ought to be split off
into a separate package? In this way, any project using docbook and a
customization layer need only produce a rpm/whatever of that customization
layer.

Rahul

Re: Docbook tools

[Mark Galassi]

    Rahul> Maybe the "canonical docbook RPMS should include the KDE
    Rahul> customization layer(which IMO does a aesthetically nicer
    Rahul> job than Norm's defaults, for admonitions at the very
    Rahul> least), or cygnus-both.dsl ought to be split off into a
    Rahul> separate package? In this way, any project using docbook
    Rahul> and a customization layer need only produce a rpm/whatever
    Rahul> of that customization layer.

I agree: this is a good plan.  I would actually do it slithly
differently: make a "docbook-customizations" package which has a bunch
of them, and encourage everyone to contribute to that common package.

Re: Docbook tools

[Eric Bischoff]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 1154 bytes --]

Le Tue, 07 Sep 1999, Rahul Dave a écrit :
> Maybe the "canonical docbook RPMS should include the KDE customization
> layer(which IMO does a aesthetically nicer job than Norm's defaults, for
> admonitions at the very least), or cygnus-both.dsl ought to be split off
> into a separate package? In this way, any project using docbook and a
> customization layer need only produce a rpm/whatever of that customization
> layer.

Well, KDE's parametrization is very short and may not be of big interest to
others, but I don't oppose that. Of course I need to have the advice of other
folks here at KDE.

Be aware that some features of this parametrization may seem
restrictive or problematic to others : for example, we make the IDs mandatory
for book's chapters, so that all HTML generated files have "human-readable"
names. This may shortly become a pain in the neck.

Eric
--
 __________________________________________________
     .~.    "Release of Windows 2000 has been
     /V\      postponed until January 1, 1901"
   //   \\
  /(     )\ 
    ^^-^^
 __________________________________________________
Eric Bischoff - mailto:ebisch@cybercable.tm.fr

Re: Docbook tools

[Eric Bischoff]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 6248 bytes --]

Dear Mark,

Le Tue, 07 Sep 1999, Mark Galassi a écrit :
>     Eric> The DocBook team at KDE has also developped some tools that
>     Eric> could prove of some interest for other users, such as a
>     Eric> crash course to DocBook that people report to be of
>     Eric> quality. Have a look at
>     Eric> http://www.kde.org/documentation/docbook/index.html .
> 
> This seems to overlap a lot with my tutorial, as others have already
> mentioned.  Nik's FreeBSD DocBook tutorial (which started out with
> mine) also overlaps.  Some day...

I talked recently about that with Guy Brand, who is on this list as well and who
is my next block neighbour ;-). Read carefully both tutorials and you will see
that there is very few overlapping in the contents. They overlap in the sense
that they intend to do the same thing : teach docbook to newcomers. But they
take two different approaches :
- Your strategy : explain the concepts (descriptive markup, ...), don't teach
the tags (the reference manual is there for that), go quickly to more advanced
concepts (such as the parts of SGML syntax that may be useful in DocBook, such
as parameter entities)
- David Rugge's Strategy : explain the purpose of DocBook, compare it with
LinuxDoc, give a detailed explaination of more common tags (admonitions, lists,
metainformation, ...), omit the more advanced tags (glossary, index, ...),
remain basic, focus on KDE needs

I don't know FreeBSD tutorial but I'm sure that it also has its own
particularities. We (I and Guy Brand) went to the conclusion that we should
merge everything, and Guy's suggestion was to do a progression in the
level of difficulty of what is teached. I imagine a framework like :
- start with your introduction
- add a detailed section about installation and usage of the docbook-tools
- then go to David's explanation of the basic tags
- then explain more advanced tags
- then switch to your explanations about what may be useful in SGML
- as Guy Brand would like, explain all the parametrization stuff (DTD,
stylesheet).

As Guy Brand said, Linux urgently needs a DocBook-HOWTO. This document could
be based on this merging work (or would the result be too long for an HOWTO???)

> The packages are all very different, and they can work with other goals,
> so I do not see any reason to combine them.

The reason would be : simplify installation. Download ONE thing, and make a
single ./configure, make, make install. But, as you say, there are many problems
linked with that idea.

> The reason is so that you can process both 3.0 and 3.1 DocBook
> documents.  If you look at the mailing list archives, my most recent
> large announcement talked about that in a bit more detail.

I read it just after posting. Sorry. ;-)

> No *immediate* help, except that jadetex uses it, and it used to not
> come with a basic TeX distribution.  It does now, but I'm not sure
> about the version numbers.  Next time I put out a package, I will see
> if I can do without the hyperref stuff :-)

I am using more or less the same versions that you have packaged, and I didn't
need it. But, if I remember well, I needed another TeX package that was not
installed on my system. Was it Babel ? I regret I didn't write that down :-(.

> * I strongly recommend that you use the same RPM distribution of tools
>   that we use (I'm also trying to get the Debian guys to start working
>   from common source).

This is what I am here for ;-)

>  You should participate in the software effort
>   (it's not hard) so that we can come up with a whole collection of
>   customizations for the stylesheets.  Ideally there should be the
>   Cygnus customization (which is rather small), the GNOME one, the KDE
>   one, the FreeBSD one, the "linux documentation project" one, and so
>   forth.

You can already have a look at KDE's customization at
http://www.kde.org/documentation/docbook . There is a DTD and a DSL. Very
short files, because we have tried hard to change as few things that we could.
Be also aware that we have started this docbook stuff very short time ago.

>  I would like them all to be easy switches to "db2html" and
>   the other "db2*" scripts.  I'll talk about this more some other
>   time, when I outline my ideas for future enhancements.

About that point, I'm wondering right now how I could make KDE's scripts
kdb2html and kdb2ps rely on your own scripts, instead of re-writing them from
scratch.

> * I would merge the tutorials together.  Take a look at mine
>   ( http://nis-www.lanl.gov/~rosalia/docbook-intro.html ) and let me
>   know if we can merge some of your beef with mine, and then maybe
>   make a KDE-specific appendix.

It looks like that everyone had the same idea ;-).

The KDE-specific stuff could go to a separate file.

About this merging project : I'm very interested, but I don't have the time
right now. After KDE's conversion to DocBook, sure.

> * I am delighted about the possibility of KDE/GNOME cooperation in
>   documentation issues.  We should talk about some aspects of this,
>   like directory layout, help-topics locations, common Makefile.am
>   documentaiton target rules, and maybe equivalent help menus.  We'd
>   teach the other parts of the GNOME and KDE teams how well we work
>   together on common standards.

I am no "official KDE representative", so I don't have the right to speak in
name of the KDE project apart from technical issues linked with documentation.
But I think I reveal no state secret if I say that I spoke about that
subject with Matthias Ettrich (KDE project founder) in Strasbourg and in
Kaiserslautern, and that I also heard him interviewed by Linux Magazine France
journalists : he has nothing against both projects taking common approaches, on
the contrary. They already did on several issues (drag'n'drop protocol, etc...).

>  And then we can also teach the
>   Russians and the Chinese to live happily together.

Well, that point makes no problem in the KDE project ;-)

Eric
--
 __________________________________________________
     .~.    "Release of Windows 2000 has been
     /V\      postponed until January 1, 1901"
   //   \\
  /(     )\ 
    ^^-^^
 __________________________________________________
Eric Bischoff - mailto:ebisch@cybercable.tm.fr

Re: Docbook tools

[Jason Molenda]

> On Sun, Sep 05, 1999 at 09:30:26PM -0400, Eric Bischoff wrote:

> I was planning to package all this stuff all together - exactly what
> you have done at Cygnus.

Just to be clear on this point, all the credit for the DocBook packages
should go to Mark Galassi, not Cygnus.  These were originally started by
people working at Cygnus, and Mark Galassi stepped up to maintain them.
He has decided to keep maintaining them even though he has left Cygnus
(he's now off playing rocket scientist :-).

Cygnus provides hosting services for this software project, but that's
about the extent of Cygnus' contribution.  A bunch of us use the tools
here at Cygnus, of course, but I don't think anyone at Cygnus is really
contributing to the tools these days.


Jason
Free the Software!

Re: Docbook tools

[Derek Simkowiak]

> > I was planning to package all this stuff all together - exactly what
> > you have done at Cygnus.
> 
> Just to be clear on this point, all the credit for the DocBook packages
> should go to Mark Galassi, not Cygnus. 

	Mark:  THANK YOU!

	Before finding these packages, I hunted all over for various
packages which contained the DocBook DTD, the SGMLtools files, jade, other
stuff from Oasis, and even some custom in-house stuff from
O'Reilly&Associates.  Finding these packages was a godsend--not to mention
the tutorial (I'm a newbie at this).

	These packages are already linked from the
http://developer.gnome.org , and now it looks like they will become the
"standard" packages for the KDE team.  Also, I will tell my editor at
O'Reilly about this and they're likely to become the defacto for O'Reilly
authors who want to write in SGML/DocBook.

	In case it's still not clear: the work Mark is doing is incredibly
important and will become even moreso as more people start to write Gnome,
KDE, and O'Reilly documentation in SGML format.


> He has decided to keep maintaining them even though he has left Cygnus
> (he's now off playing rocket scientist :-).

	If it's not inappropriate to ask... what's the "rocket scientist"
project?  Something cool Mark can talk about?


--Derek

Re: Docbook tools

[Mark Galassi]

    >> Just to be clear on this point, all the credit for the DocBook
    >> packages should go to Mark Galassi, not Cygnus.

    Derek> 	Mark: THANK YOU!

Dude, thanks, but my effort is negligible compared to the guys who
wrote the major software.

    Derek> Finding these packages was a godsend--not to mention the
    Derek> tutorial (I'm a newbie at this).

I feel like Wallace, in "Wallace and Gromit -- A Close Shave", saying
"windows are our speciality".  I guess I'm referring not to "windows",
but rather to getting something that works out of the box.

But the real godsend will be if we can pull together with the
SGMLTools effort and do the automake/autoconf stuff I mentioned in a
message earlier today.

    Derek> Also, I will tell my editor at O'Reilly about this and
    Derek> they're likely to become the defacto for O'Reilly authors
    Derek> who want to write in SGML/DocBook.

Since Norm Walsh used to work for O'Reilly, and O'Reilly used to host
the Davenport group, I thought they would have something they can
offer to prospective authors.  Maybe not.

So, dude, tell me what your O'Reilly book is about!

    Derek> 	In case it's still not clear: the work Mark is doing
    Derek> is incredibly important and will become even moreso as more
    Derek> people start to write Gnome, KDE, and O'Reilly
    Derek> documentation in SGML format.

O'Reilly has been using properly customized DocBook for many of its
books for quite a while.

    Derek> 	If it's not inappropriate to ask... what's the "rocket
    Derek> scientist" project?  Something cool Mark can talk about?

It's quite open, really: I'm an astrophysicist, although I have
frequently been on the verge of being defrocked becuase I like to hack
a lot.

Right now I'm working on the HETE-2 satellite, which is a small
satellite designed to collect information on Gamma Ray Bursts (a very
trendy, exciting, and difficult phenomenon in astrophysics).

I'm designing and writing the flight software for the more complex of
the instruments: my software triggers on a gamma ray burst (by looking
at X-ray and Gamma ray data), figures out its position on the sky (by
deconvolving the X-ray data with a coded mask pattern), and handles
instrument housekeeping and so forth.

Once HETE-2 launches, I might finally actually have a chance at
analyzing and publishing on some astrophysics data, at which point I
can go back to some of my ideas on grand unification of scientific
software.

Re: Docbook tools

[Jochem Huhmann]

 Mark Galassi <rosalia@lanl.gov> wrote:
> But the real godsend will be if we can pull together with the
> SGMLTools effort and do the automake/autoconf stuff I mentioned in a
> message earlier today.

Is this effort limited to get jade and DSSSL-related stuff going?

SGMLTools did so and suffered a lot by doing so. There are docbook2man
translators in perl (which allows to write man pages as REFENTRY
elements) and there is also a docbook2texinfo translator (really great
if you need info as documentation format, especially when working with
emacs, but also an alternative approach to get printed documentation
via LaTeX).

Would be nice if there would be a central store to get all this, with
a unified interface and such...


        Jochem

-- 
Hi! I'm a .signature virus! Copy me into your ~/.signature to help me spread!

Re: Docbook tools

[Derek Simkowiak]

> Dude, thanks, but my effort is negligible compared to the guys who
> wrote the major software.

	Not when you're brand new to the subject.  The software's no good
if you can't figure out how to get it working.

	But yes, the authors of the tools deserve a heartfelt Thank You as
well :).

> but rather to getting something that works out of the box.

	People don't realize just how important that is.

> Since Norm Walsh used to work for O'Reilly, and O'Reilly used to host
> the Davenport group, I thought they would have something they can
> offer to prospective authors.  Maybe not.

	They did, but the person maintaining that appearantly left
recently and there was some confusion as to what worked and what didn't.  
I'm sure they'll get things straightened out soon, but in the meantime
these tools are very helpful.

> So, dude, tell me what your O'Reilly book is about!

	Programming Gnome applications.  The target audience will mostly
be Windows programmers looking to get into Linux development, so it
includes some introductory information on using the GNU toolset.  The SGML
source (and HTML versions) will be available free online once it's done
(like Havoc Pennington's book).

> It's quite open, really: I'm an astrophysicist, although I have
> frequently been on the verge of being defrocked becuase I like to hack
> a lot.

	I may be sending you a personal message later on... My original
"dream" was to go into Physics, but it was really hard to concentrate on
school when people will pay you $100+/hour to develop (read: Hack) under
Linux/Unix. I'm thinking about going back to school to get into Physics
again...


Thanks,
Derek