RE: Where, what and how - The future of DocBook

RE: Where, what and how - The future of DocBook

[Peter Ring]

Put this at the bottom of your XML files:

<!-- Keep this comment near the end of the file
Local variables:
mode: xml
sgml-declaration: "xhtml1.dcl"
End:
-->

Replace "xhtml1.dcl" with the pathname of the correct declaration, e.g.,
"/usr/lib/sgml/declaration/xml.dcl".

Kind regards
Peter Ring


-----Original Message-----
From: Mark Johnson [ mailto:mark@phy.duke.edu ]
Sent: 6. december 2000 17:05
To: docbook-tools-discuss@sourceware.cygnus.com
Subject: Re: Where, what and how - The future of DocBook

...

You might want to add that validation requires the XML declaration (xml.dcl
or xml.decl) rather than docbook.dcl.

In your .emacs you may have something like:

    (setq sgml-declaration "/usr/lib/sgml/declaration/docbook.dcl")

For XML I tried the following, but for some reason it doesn't work:

    (setq sgml-xml-declaration "/usr/lib/sgml/declaration/xml.dcl")

...

More psgml tips...

[Mark Johnson]

> Put this at the bottom of your XML files:
>
> <!-- Keep this comment near the end of the file
> Local variables:
> mode: xml
> sgml-declaration: "xhtml1.dcl"
> End:
> -->
>

Thanks for the tip. I never thought to do that.

It'd be nice if when in xml-mode psgml used xml.dcl, and a different one when
in sgml-mode. Does anyone know if/how I can tweak my .emacs so emacs will use
different declarations according to the mode--sgml or xml?

As long as we're talking local-variables and passing tips for good
documentation, one of my faves is using the sgml-parent-document variable.

Setting this variable allows you to edit the various sub-files that compose a
larger document without having to insert a DOCTYPE statement at the top of
them. And to do it in a dtd-aware fashion.

Put another way, there's no need to put a DOCTYPE statement in the chapter
files of a book while editing them.

The problem I had was that I couldn't understand the explanation in the psgml
docs telling me how to do it.  I think I finally learned from a post on this
or docbook-apps. Most subscribers probably know this, but I'll explain how to
do it for those who don't.

Here's an example:

    Parent file = mybook.xml
    Root element of parent file = <book>

    Child file = chapter2.xml file
    Root element of child file = <chapter>

put the following at the bottom:
    <!--
    Local variables:
    mode: xml
    sgml-parent-document:("mybook.xml" "book" "chapter")
    End:
    -->

the general pattern that works for me is:

    sgml-parent-document:("parent-filename" "root-element-of-parent-file"
"root-element-of-current-file")

Which I think is easier to understand than the full psgml explanation. On
first encounter, anyway. Here's the psgml explanation:

------------------------------------------------
Documentation:
* Used when the current file is part of a bigger document.

The variable describes how the current file's content fit into the element
hierarchy. The variable should have the form

  (PARENT-FILE CONTEXT-ELEMENT* TOP-ELEMENT (HAS-SEEN-ELEMENT*)?)

PARENT-FILE is a string, the name of the file contatining the
  document entity.
CONTEXT-ELEMENT is a string, that is the name of an element type.
  It can occur 0 or more times and is used to set up
  exceptions and short reference map. Good candidates
  for these elements are the elements open when the
  entity pointing to the current file is used.
TOP-ELEMENT is a string that is the name of the element type
  of the top level element in the current file. The file
  should contain one instance of this element, unless
  the last (lisp) element of sgml-parent-document is a
  list. If it is a list, the top level of the file
  should follow the content model of top-element.
HAS-SEEN-ELEMENT is a string that is the name of an element type. This
         element is satisfied in the content model of top-element.

Setting this variable automatically makes it local to the current buffer.
-------------------------------------------------

Of course now I understand the explanation above. What's that saying about
hindsight?

Cheers,
Mark

>
> Replace "xhtml1.dcl" with the pathname of the correct declaration, e.g.,
> "/usr/lib/sgml/declaration/xml.dcl".
>
> Kind regards
> Peter Ring
>
> -----Original Message-----
> From: Mark Johnson [ mailto:mark@phy.duke.edu ]
> Sent: 6. december 2000 17:05
> To: docbook-tools-discuss@sourceware.cygnus.com
> Subject: Re: Where, what and how - The future of DocBook
>
> ...
>
> You might want to add that validation requires the XML declaration (xml.dcl
> or xml.decl) rather than docbook.dcl.
>
> In your .emacs you may have something like:
>
>     (setq sgml-declaration "/usr/lib/sgml/declaration/docbook.dcl")
>
> For XML I tried the following, but for some reason it doesn't work:
>
>     (setq sgml-xml-declaration "/usr/lib/sgml/declaration/xml.dcl")
>
> ...

Re: More psgml tips...

[Michael Wiedmann]

Mark Johnson wrote:
...
> Setting this variable allows you to edit the various sub-files that compose a
> larger document without having to insert a DOCTYPE statement at the top of
> them. And to do it in a dtd-aware fashion.
... 
> Here's an example:
> 
>     Parent file = mybook.xml
>     Root element of parent file = <book>
> 
>     Child file = chapter2.xml file
>     Root element of child file = <chapter>
> 
> put the following at the bottom:
>     <!--
>     Local variables:
>     mode: xml
>     sgml-parent-document:("mybook.xml" "book" "chapter")
>     End:
>     -->

Good tip, Mark!

Translated to a "website" document this would mean:

<!--
Local variables:
mode: xml
sgml-parent-document:("myfile.xml" "website" "webpage")
End:
-->

Correct?

Michael
-- 
office:  michael.wiedmann@detewe.de
private: mw@miwie.in-berlin.de                 http://www.miwie.org/
         mw@miwie.org                          http://wap.miwie.org/

More psgml tips...

[Mark Johnson]

> Put this at the bottom of your XML files:
>
> <!-- Keep this comment near the end of the file
> Local variables:
> mode: xml
> sgml-declaration: "xhtml1.dcl"
> End:
> -->
>

Thanks for the tip. I never thought to do that.

It'd be nice if when in xml-mode psgml used xml.dcl, and a different one when
in sgml-mode. Does anyone know if/how I can tweak my .emacs so emacs will use
different declarations according to the mode--sgml or xml?

As long as we're talking local-variables and passing tips for good
documentation, one of my faves is using the sgml-parent-document variable.

Setting this variable allows you to edit the various sub-files that compose a
larger document without having to insert a DOCTYPE statement at the top of
them. And to do it in a dtd-aware fashion.

Put another way, there's no need to put a DOCTYPE statement in the chapter
files of a book while editing them.

The problem I had was that I couldn't understand the explanation in the psgml
docs telling me how to do it.  I think I finally learned from a post on this
or docbook-apps. Most subscribers probably know this, but I'll explain how to
do it for those who don't.

Here's an example:

    Parent file = mybook.xml
    Root element of parent file = <book>

    Child file = chapter2.xml file
    Root element of child file = <chapter>

put the following at the bottom:
    <!--
    Local variables:
    mode: xml
    sgml-parent-document:("mybook.xml" "book" "chapter")
    End:
    -->

the general pattern that works for me is:

    sgml-parent-document:("parent-filename" "root-element-of-parent-file"
"root-element-of-current-file")

Which I think is easier to understand than the full psgml explanation. On
first encounter, anyway. Here's the psgml explanation:

------------------------------------------------
Documentation:
* Used when the current file is part of a bigger document.

The variable describes how the current file's content fit into the element
hierarchy. The variable should have the form

  (PARENT-FILE CONTEXT-ELEMENT* TOP-ELEMENT (HAS-SEEN-ELEMENT*)?)

PARENT-FILE is a string, the name of the file contatining the
  document entity.
CONTEXT-ELEMENT is a string, that is the name of an element type.
  It can occur 0 or more times and is used to set up
  exceptions and short reference map. Good candidates
  for these elements are the elements open when the
  entity pointing to the current file is used.
TOP-ELEMENT is a string that is the name of the element type
  of the top level element in the current file. The file
  should contain one instance of this element, unless
  the last (lisp) element of sgml-parent-document is a
  list. If it is a list, the top level of the file
  should follow the content model of top-element.
HAS-SEEN-ELEMENT is a string that is the name of an element type. This
         element is satisfied in the content model of top-element.

Setting this variable automatically makes it local to the current buffer.
-------------------------------------------------

Of course now I understand the explanation above. What's that saying about
hindsight?

Cheers,
Mark

>
> Replace "xhtml1.dcl" with the pathname of the correct declaration, e.g.,
> "/usr/lib/sgml/declaration/xml.dcl".
>
> Kind regards
> Peter Ring
>
> -----Original Message-----
> From: Mark Johnson [ mailto:mark@phy.duke.edu ]
> Sent: 6. december 2000 17:05
> To: docbook-tools-discuss@sourceware.cygnus.com
> Subject: Re: Where, what and how - The future of DocBook
>
> ...
>
> You might want to add that validation requires the XML declaration (xml.dcl
> or xml.decl) rather than docbook.dcl.
>
> In your .emacs you may have something like:
>
>     (setq sgml-declaration "/usr/lib/sgml/declaration/docbook.dcl")
>
> For XML I tried the following, but for some reason it doesn't work:
>
>     (setq sgml-xml-declaration "/usr/lib/sgml/declaration/xml.dcl")
>
> ...

RE: Where, what and how - The future of DocBook

[Peter Ring]

Put this at the bottom of your XML files:

<!-- Keep this comment near the end of the file
Local variables:
mode: xml
sgml-declaration: "xhtml1.dcl"
End:
-->

Replace "xhtml1.dcl" with the pathname of the correct declaration, e.g.,
"/usr/lib/sgml/declaration/xml.dcl".

Kind regards
Peter Ring


-----Original Message-----
From: Mark Johnson [ mailto:mark@phy.duke.edu ]
Sent: 6. december 2000 17:05
To: docbook-tools-discuss@sourceware.cygnus.com
Subject: Re: Where, what and how - The future of DocBook

...

You might want to add that validation requires the XML declaration (xml.dcl
or xml.decl) rather than docbook.dcl.

In your .emacs you may have something like:

    (setq sgml-declaration "/usr/lib/sgml/declaration/docbook.dcl")

For XML I tried the following, but for some reason it doesn't work:

    (setq sgml-xml-declaration "/usr/lib/sgml/declaration/xml.dcl")

...

Re: More psgml tips...

[Michael Wiedmann]

Mark Johnson wrote:
...
> Setting this variable allows you to edit the various sub-files that compose a
> larger document without having to insert a DOCTYPE statement at the top of
> them. And to do it in a dtd-aware fashion.
... 
> Here's an example:
> 
>     Parent file = mybook.xml
>     Root element of parent file = <book>
> 
>     Child file = chapter2.xml file
>     Root element of child file = <chapter>
> 
> put the following at the bottom:
>     <!--
>     Local variables:
>     mode: xml
>     sgml-parent-document:("mybook.xml" "book" "chapter")
>     End:
>     -->

Good tip, Mark!

Translated to a "website" document this would mean:

<!--
Local variables:
mode: xml
sgml-parent-document:("myfile.xml" "website" "webpage")
End:
-->

Correct?

Michael
-- 
office:  michael.wiedmann@detewe.de
private: mw@miwie.in-berlin.de                 http://www.miwie.org/
         mw@miwie.org                          http://wap.miwie.org/

Re: Where, what and how - The future of DocBook

[Michael Smith]

Alan W. Irwin <irwin@beluga.phys.uvic.ca> writes:

> I am a member of a two-man team that converted a largish piece (more
> than 100 pages) of technical documentation from latexinfo to DocBook
> 4.1 XML. [...]
>
> Since the conversion was completed I have been entering lots of
> extra content with an ordinary editor (jed). I understand there is a
> great DocBook interface available with emacs, but I haven't bothered
> with it yet because it is not really needed. From my experience I
> would assert you don't need any special tool to edit and improve
> documentation written in DocBook. The tags that are ordinarily used
> are easy to memorize. Of course, it probably helps that I am a good
> touch typist. If you don't have that skill I guess you need to find
> some tool that gives you WYSIWYG. But it wasn't necessary in my
> case, and I suspect that is true for most documenters.

Yipes -- all due respect, but I think your suspicion may be way off.

The big advantage of an editor like Emacs/psgml is that it takes much
of the guesswork out of document authoring. Validating editors by
design make it hard to produce invalid documents. Using a validating
editor, you really have to go out of your way to make something that
won't validate. Only way you can do it is to type tags in manually --
which you should never need to do with a good XML editing app.

Sure, jed's great (so's Vim -- better syntax highlighting), but if
you've never used a validating editor like Emacs/psgml, you don't know
what you're missing.

I read a thread on the LDP list in which a writer said that one
advantage of LinuxDoc was its short element names. It baffled me why
he would care how long the names were -- until I realized he was
probably typing them by hand using a regular text editor.

Once I realized that, I was baffled as to why -- when Emacs/psgml is
free, great, and so widely used -- why any skilled Linux user would
rely on a regular (non-SGML-validating) editor to work with XML/SGML.

First of all, it ain't quicker -- don't care how fast you can type.
And although it's great to memorize as much of DocBook as you can, I
wonder what kind of agreement you'd get on what tags are "ordinarily
used". I think that depends very much on what you're documenting. 

Confronted with DocBook's 375 elements (including 100+ "inline"
elements that can occur in paragraphs) and 100+ attributes, I doubt
that "most documentors" would find a validating editor uneccessary.

Most of the DocBook users I know (and I include myself) are not so
familiar with the DTD that we can always judge with confidence what
elements and attributes are -valid/required- where -- and why bother
when you've got a DTD-aware validating editor to tell you that?

In fact, one of the main concerns I hear from SGML/XML authors --
especially new ones -- is that their editing tools just aren't smart
enough, and don't go far enough in simplifying the editing process.

No, I wouldn't suggest to anyone that they author DocBook docs using
jed or any other non-validating editor -- unless they've got a lot of
extra time on their hands, really enjoy typing, and really like the
process of running documents through a parser, post-authoring, and
fixing them manually to get them to validate.

  -- Mike Smith

-- 
Michael Smith          mailto:smith@xml-doc.org
XML-DOC                http://www.xml-doc.org/

Re: Where, what and how - The future of DocBook

[Craig Boone]

Gregory Leblanc wrote:
> 
> 
> Take a look at the LDP Authors Guide
> http://www.LinuxDoc.org/LDP/LDP-Author-Guide/
> It's got a great deal of information on what the LDP is using.  I'm
> actually working on a jade wrapper using make rather than the stuff that
> the docbook tools project has done, as this is exactly what make is
> designed for.  I hope to have something worth showing off early next
> year.
> 
>     Greg


Thanks for the feedback.  I really appreciate it.

C-

-- 
Craig A. Boone          craig@estinc.com
Technical Writer        Enhanced Software Technologies, Inc.
Ph:  602.470.1115       Fax:  602.470.1116
                        www.estinc.com

After the game, the king and pawn go into the same box. --Italian
Proverb

Loyalty to a petrified opinion never yet broke a chain or freed a human
soul.
--Mark Twain

Re: Where, what and how - The future of DocBook

[Michael Wiedmann]

Eric Bischoff wrote:
... 
> and a source of documentation: the crash-course to DocBook at
> 
>         http://www.caldera.de/~eric/crash-course

Forbidden :-(
but http://www.caldera.de/~eric/ works :-)

One remark/question:
In "App. B. Emacs PSGML mode tips" your write

"Note: PSGML mode is for SGML DocBook. It does not support
 XML DocBook."

Is this really true? 
I'm editing my XML DocBook files using PSGML and didn't run into 
any problems up to now.

> (this guide will be integrated to Debian soon, BTW).

That's good news!

Michael
-- 
office:  michael.wiedmann@detewe.de
private: mw@miwie.in-berlin.de                 http://www.miwie.org/
         mw@miwie.org                          http://wap.miwie.org/

Re: Where, what and how - The future of DocBook

[Eric Bischoff]

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

Sorry if I'm repeating myself, but:

Did someone ever succeed in converting a Korean/Japanese/Chinese DocBook
file into PDF or PostScript? I need help on this.

-- 
Éric Bischoff                                  mailto:e.bischoff@noos.fr
-- Support your government, give Echelon/Carnivore something to parse --
AMTAS ATMD ATSC Abdullah Allah  communist CIA DD2-N DISA DoD GRU Gregori
Irak  Iran KGB  Kurdish LSD  NATO NSTD  Natasha  ORD RTEM  Russia  STRAP
Saddam Hussein  TSP  Yugoslavia   attack  bank  bomb  classfield  cocain
compromise defense  democracy  destroy  destruct  detonator  directorate
elections enforce extasy force  foreign embassy government grass hashish
heroin   illegal  information   international  military systems  missile
million dollars   nuclear  policital   pot  power   presidental  project
restricted data  revolution  rule the world sensitive  smuggle spy steal
system  takeover  terrorist  top-secret  warmod  warrior-T  weapon  weed
------------------------------------------------------------------------

Re: Where, what and how - The future of DocBook

[Eric Bischoff]

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

> For the "full" documentation, you can try http://docbook.org --- and
> buy the O'Reilly book; it's very good!
> 
> Standard Linux distributions such as Conectiva, Mandrake, Red Hat,
> Debian, SuSE already have packages for DocBook usage.


I'd like to remind another source of packages: The "docbook-tools" at 

	ftp://sourceware.cygnus.com/pub/docbook-tools/new-trials/

and a source of documentation: the crash-course to DocBook at

	http://www.caldera.de/~eric/crash-course

(this guide will be integrated to Debian soon, BTW).

-- 
Éric Bischoff                                  mailto:e.bischoff@noos.fr
-- Support your government, give Echelon/Carnivore something to parse --
AMTAS ATMD ATSC Abdullah Allah  communist CIA DD2-N DISA DoD GRU Gregori
Irak  Iran KGB  Kurdish LSD  NATO NSTD  Natasha  ORD RTEM  Russia  STRAP
Saddam Hussein  TSP  Yugoslavia   attack  bank  bomb  classfield  cocain
compromise defense  democracy  destroy  destruct  detonator  directorate
elections enforce extasy force  foreign embassy government grass hashish
heroin   illegal  information   international  military systems  missile
million dollars   nuclear  policital   pot  power   presidental  project
restricted data  revolution  rule the world sensitive  smuggle spy steal
system  takeover  terrorist  top-secret  warmod  warrior-T  weapon  weed
------------------------------------------------------------------------

Re: Where, what and how - The future of DocBook

[Peter Toft]

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

On 4 Dec 2000, Norman Walsh wrote:

> | Fine - which tools are available for writing
> | SGML/DocBook on Linux+xBSD or Windows?
>
> The future is XML, not SGML.

Agree. Can we get MANY people to use the tools?
How do we get the tools working?
- Which tools should the ordinary person download?
- How are they installed?
- Where is the first "lets try it" - example
- Where is the tutorials?
- Where is the full documentation?
- Can we get standard Linux/*BSD distributions
  to carry the tools?

These the the *KEY* questions to answer in the best
possible way. I am sorry to say that I find it hard to
find it.

>
> | - Emacs and alike tools?
>
> Naturally.

;-)))

>
> | - Any WYSIWYG editors?
>
> That said, for Windows there are lots of XML editing tools coming
> online. For production environments, I would recommend Arbortext's
> Epic (disclaimer: I used to work for them). SoftQuad's XMetaL is less
> expensive.
>
> | - Any *fast* syntax verification system
>
> James Clark's SP.

URL - again, download?, install?, howto? + full docs.

>
> | - and what is being made in general
>
> What is being made of what in general?

Who is making what at the moment for DocBook?

>
> | Many companies don't accept DocBook - why?
>
> Many companies do. Bug ones. With lots of documentation: Sun, HP,
> Novell, etc. Who doesn't accept it (and why do you care that they
> don't?)

Eg. IMT-2000 standardization (UMTS) - check
http://www.3gpp.org -> all the work is Word-files.

I care a lot. I find that Word is eating WAY to much of
the areas, where DocBook could have been cool. I think
Word is preferred for many companies today - many do
not consider DocBook - that is a shame - we can all
agree on that!




>
> | Can't we do better???
>
> I'm sure we can.

We have to IMHO!

>
> | What is the future for SGML/DocBook versus XML/DocBook
> | - again also regarding tools, the work efford going on
> | at the moment etc.
>
> XML is the future. But since XML is SGML, there's no loss here. You
> can continue to use your favorite SGML tools. But I don't expect any
> more SGML tools to be written. Ever.

Ok ;-))

-- 
Peter Toft, Ph.D. [pto@sslug.dk] http://www.sslug.dk/~pto

"You don't win a battle by asking, `Will we win?'
You win it by doing your best to win" - Richard M Stallman

LinuxKonference i København: http://LinuxForum.dk/

Re: Where, what and how - The future of DocBook

[Gregory Leblanc]

> Gregory Leblanc wrote:
> 
> > I've gotten around this the easy way, I don't use pdfjadetex.  Instead,
> > I use a tool called htmldoc, which convers from HTML to PS/PDF, and does
> > a VERY nice job at it.  The only thing that's missing is that it doesn't
> > convert the external (href) hyperlinks to something useful along the
> > way.  I can do this with jade, but jade is slow.
> > 
> >     Greg
> 
> Is htmldoc something that you created, or is it something that's
> available for download?  I can't seem to get any of the pdf/ps


I guess this is what I get for not posting a
URL.  :-)  http://www.easysw.com/htmldoc/  htmldoc is GPL, so use it how
you like.


> conversions to occur properly with the DocBook tools that I have.  I'm
> using the db2pdf and db2ps scripts and all they seem to do is explode
> and spew latex errors everywhere.  I can write picture-perfect sgml and
> it makes lovely html conversions, but it doesn't do me much good if I
> can't get it printed. 


We use just straight Jade, as the db2 scripts weren't very portable, and
because we NEED good PS/PDF output.  The only thing that we're still
working on is good text support.


> I've been monitoring this list and watching all of the "Future of
> DocBook" threads and I gotta say it's a great project and I'd love to be
> able to set it as a standard to create all of my documentation. 
> However, I just can't seem to get a dependable set of tools and solidly
> implement them.  Suggestions?


Take a look at the LDP Authors Guide
http://www.LinuxDoc.org/LDP/LDP-Author-Guide/
It's got a great deal of information on what the LDP is using.  I'm
actually working on a jade wrapper using make rather than the stuff that
the docbook tools project has done, as this is exactly what make is
designed for.  I hope to have something worth showing off early next
year.

    Greg

Re: Where, what and how - The future of DocBook

[Eric Bischoff]

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

Mark Johnson wrote:
> 
> Eric Bischoff wrote:
> 
> > Michael Wiedmann wrote:
> > >
> > > I'm editing my XML DocBook files using PSGML and didn't run into
> > > any problems up to now.
> >
> > Did you have to do something in special that would be relevant to
> > include in the doc at this place?
> 
> You might want to add that validation requires the XML declaration (xml.dcl
> or xml.decl) rather than docbook.dcl.

Okay. I now include this file in sgml-common package.

> In your .emacs you may have something like:
> 
>     (setq sgml-declaration "/usr/lib/sgml/declaration/docbook.dcl")
> 
> For XML I tried the following, but for some reason it doesn't work:
> 
>     (setq sgml-xml-declaration "/usr/lib/sgml/declaration/xml.dcl")
> 
> So I use:
> 
>         (setq sgml-declaration "/usr/lib/sgml/declaration/xml.dcl")
> 
> The paths are probably different on a redhat machine.
> 
> ...my $0.02

I will try to incorporate those lines to the psgml package or to the
doc. Thanks for your two cents ;-).

-- 
+----------------------------------------------------------------------+
| Éric Bischoff                              mailto:e.bischoff@noos.fr |
+----------------------------------------------------------------------+

Re: Where, what and how - The future of DocBook

[Gregory Leblanc]

> That said, you have been a good advocate for emacs/psgml (and so was my
> partner in the project) so I will probably try it next time, but I don't
> regret for a moment doing my first DocBook project this simple and
> straightforward way. I seem to learn the best if I solve problems with
> low-end tools to start, and then move on up to more sophisticated tools
> later on.  YMMV, of course.


I dove into psgml when I first started writing, and it was a really nice
learning tool, especially combined with the templates that the GNOME Doc
Project has.  I've since become one of the most knowledgeable docbook
people actively involved in that project.

> This has been an interesting discussion about methods and perhaps even
> valuable as well, but I sure wish I could get as quick a response on this
> list to the practical problem of Cygnus pdfjadetex not working in the
> latest release.


I've gotten around this the easy way, I don't use pdfjadetex.  Instead,
I use a tool called htmldoc, which convers from HTML to PS/PDF, and does
a VERY nice job at it.  The only thing that's missing is that it doesn't
convert the external (href) hyperlinks to something useful along the
way.  I can do this with jade, but jade is slow.

    Greg

Re: Where, what and how - The future of DocBook

[Craig Boone]

Gregory Leblanc wrote:

> I've gotten around this the easy way, I don't use pdfjadetex.  Instead,
> I use a tool called htmldoc, which convers from HTML to PS/PDF, and does
> a VERY nice job at it.  The only thing that's missing is that it doesn't
> convert the external (href) hyperlinks to something useful along the
> way.  I can do this with jade, but jade is slow.
> 
>     Greg

Is htmldoc something that you created, or is it something that's
available for download?  I can't seem to get any of the pdf/ps
conversions to occur properly with the DocBook tools that I have.  I'm
using the db2pdf and db2ps scripts and all they seem to do is explode
and spew latex errors everywhere.  I can write picture-perfect sgml and
it makes lovely html conversions, but it doesn't do me much good if I
can't get it printed. 

I've been monitoring this list and watching all of the "Future of
DocBook" threads and I gotta say it's a great project and I'd love to be
able to set it as a standard to create all of my documentation. 
However, I just can't seem to get a dependable set of tools and solidly
implement them.  Suggestions?

-- 
Craig A. Boone          craig@estinc.com
Technical Writer        Enhanced Software Technologies, Inc.
Ph:  602.470.1115       Fax:  602.470.1116
                        www.estinc.com

After the game, the king and pawn go into the same box. --Italian
Proverb

Loyalty to a petrified opinion never yet broke a chain or freed a human
soul.
--Mark Twain

Re: Where, what and how - The future of DocBook

[Mark Johnson]

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

Eric Bischoff wrote:

> Michael Wiedmann wrote:
> >
> > I'm editing my XML DocBook files using PSGML and didn't run into
> > any problems up to now.
>
> Did you have to do something in special that would be relevant to
> include in the doc at this place?

You might want to add that validation requires the XML declaration (xml.dcl
or xml.decl) rather than docbook.dcl.

In your .emacs you may have something like:

    (setq sgml-declaration "/usr/lib/sgml/declaration/docbook.dcl")

For XML I tried the following, but for some reason it doesn't work:

    (setq sgml-xml-declaration "/usr/lib/sgml/declaration/xml.dcl")

So I use:

        (setq sgml-declaration "/usr/lib/sgml/declaration/xml.dcl")

The paths are probably different on a redhat machine.

...my $0.02


Mark


>
>
> > > (this guide will be integrated to Debian soon, BTW).
> >
> > That's good news!
>
> :-)
>
> --
> Éric Bischoff                                  mailto:e.bischoff@noos.fr
> -- Support your government, give Echelon/Carnivore something to parse --
> AMTAS ATMD ATSC Abdullah Allah  communist CIA DD2-N DISA DoD GRU Gregori
> Irak  Iran KGB  Kurdish LSD  NATO NSTD  Natasha  ORD RTEM  Russia  STRAP
> Saddam Hussein  TSP  Yugoslavia   attack  bank  bomb  classfield  cocain
> compromise defense  democracy  destroy  destruct  detonator  directorate
> elections enforce extasy force  foreign embassy government grass hashish
> heroin   illegal  information   international  military systems  missile
> million dollars   nuclear  policital   pot  power   presidental  project
> restricted data  revolution  rule the world sensitive  smuggle spy steal
> system  takeover  terrorist  top-secret  warmod  warrior-T  weapon  weed
> ------------------------------------------------------------------------

Re: Where, what and how - The future of DocBook

[Eric Bischoff]

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

Michael Wiedmann wrote:
> 
> Eric Bischoff wrote:
> ...
> > and a source of documentation: the crash-course to DocBook at
> >
> >         http://www.caldera.de/~eric/crash-course
> 
> Forbidden :-(
> but http://www.caldera.de/~eric/ works :-)


Sorry, I should have said

	http://www.caldera.de/~eric/crash-course/HTML/index.html

> One remark/question:
> In "App. B. Emacs PSGML mode tips" your write
> 
> "Note: PSGML mode is for SGML DocBook. It does not support
>  XML DocBook."
> 
> Is this really true?

Hmmm, someone else already pointed this out. I thought I removed it. On
my TODO list.

> I'm editing my XML DocBook files using PSGML and didn't run into
> any problems up to now.

Did you have to do something in special that would be relevant to
include in the doc at this place.

> > (this guide will be integrated to Debian soon, BTW).
> 
> That's good news!

:-)

-- 
Éric Bischoff                                  mailto:e.bischoff@noos.fr
-- Support your government, give Echelon/Carnivore something to parse --
AMTAS ATMD ATSC Abdullah Allah  communist CIA DD2-N DISA DoD GRU Gregori
Irak  Iran KGB  Kurdish LSD  NATO NSTD  Natasha  ORD RTEM  Russia  STRAP
Saddam Hussein  TSP  Yugoslavia   attack  bank  bomb  classfield  cocain
compromise defense  democracy  destroy  destruct  detonator  directorate
elections enforce extasy force  foreign embassy government grass hashish
heroin   illegal  information   international  military systems  missile
million dollars   nuclear  policital   pot  power   presidental  project
restricted data  revolution  rule the world sensitive  smuggle spy steal
system  takeover  terrorist  top-secret  warmod  warrior-T  weapon  weed
------------------------------------------------------------------------

Where, what and how - The future of DocBook

[Peter Toft]

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

Dudez - this is not to start a flamewar, so be positive
and think constructive now:

Many people agree that DocBook is the path to continue
along for Open Source program documentation and perhaps
also the system we should promote to use for document
handling in general.

Fine - which tools are available for writing
SGML/DocBook on Linux+xBSD or Windows?
- Emacs and alike tools?
- Any WYSIWYG editors?
- Any *fast* syntax verification system
- and what is being made in general

At the moment I write a lot in Emacs - but my mum would
not try that!!!

Many companies don't accept DocBook - why?
Can't we do better???

What is the future for SGML/DocBook versus XML/DocBook
- again also regarding tools, the work efford going on
at the moment etc.

Best regards

Peter/A DocBook user for several years now.

-- 
Peter Toft, Ph.D. [pto@sslug.dk] http://www.sslug.dk/~pto

"You don't win a battle by asking, `Will we win?'
You win it by doing your best to win" - Richard M Stallman

LinuxKonference i København: http://LinuxForum.dk/

Re: Where, what and how - The future of DocBook

[Michael Smith]

madhu <bmadi_1@yahoo.com> writes:

> On Wed, 06 Dec 2000, Eric Bischoff wrote:
> 
> > and a source of documentation: the crash-course to DocBook at
> > 
> > 	http://www.caldera.de/~eric/crash-course
> 
> i get a 403 error with this url and it tells me : Forbidden
> You don't have permission to access /~eric/crash-course/ on this
> server.

http://www.caldera.de/~eric/crash-course/HTML/index.html


-- 
Michael Smith          mailto:smith@xml-doc.org
XML-Doc                http://www.xml-doc.org/

Re: Where, what and how - The future of DocBook

[Michael Smith]

Alan, you wrote:

> Mike, I was reacting against those who implied DocBook was so
> difficult that you absolutely required sophisticated tools to deal
> with it.

Yes, sorry if I came across a too emphatically. I definitely concur
with you there -- no sophisticated (commercial?) tools are required.
Using DocBook is never more nor less complex than your needs -- that
is, what you need to encode in your document instances.

And regardless of complexity, my response to those (not you of course)
who question using DocBook for hardware/software documentation is,
-Please show me an alternative-.

I guess someone who wanted to could re-invent the wheel and come up
with a kind of subset of DocBook. But Norm Walsh and the others
guiding DocBook have already provided DocBook with a customization
layer designed to facilitate subsetting and/or enhancements. Sure,
it's not trivial to design/configure a DocBook subset -- but it's a
hell of a lot easier than with any other DTD I've ever used.

> Also, you have, IMO a weak argument about validation since it
> actually doesn't take very long to do it on a modern PC
> independently of the editing process if you do editing in one window
> and validation in another.

OK, yes maybe I overstated that. But to put things in perspective: you
mentioned that you were working on a hundred-page document.

Not to downplay the work I'm sure you put into marking up that
document, but for a lot of the doc folks I know, a hundred page
document is a walk in the park -- these people (not me, thank god
almighty) are working on things like huge "butterfly" manuals that run
to so many pages no one bothers to count them. Awful stuff.

I would not want to work on documents of that length without a
vailidating editor. Actually, wouldn't want to work on that kind of
stuff at all myself -- but I guess somebody's got to do it.

> [...] I rarely (about 4 times in the whole project) had a validation
> error. So things went really fast for the simple method I chose.
> That is an important point I hope we can agree on; DocBook ain't
> difficult and doesn't absolutely *require* sophisticated tools.

You're right of course.

> That said, you have been a good advocate for emacs/psgml (and so was
> my partner in the project) so I will probably try it next time

Very glad to hear that.

If after using psgml, you or anyone on the list has ideas on improving
psgml, I want to encourage you to help make it better -- because
Lennart Staflin has, yahoo!, recently moved the psgml source to
Sourceforge, opened it to collaborative development and set up mailing
lists for discussions along those lines. Take a look:

  http://sourceforge.net/projects/psgml

> but I don't regret for a moment doing my first DocBook project
> this simple and straightforward way. I seem to learn the best if I
> solve problems with low-end tools to start, and then move on up to
> more sophisticated tools later on. YMMV, of course.

Again, you're right -- no one can take issue with that philosophy. 

> This has been an interesting discussion about methods and perhaps
> even valuable as well, but I sure wish I could get as quick a
> response on this list to the practical problem of Cygnus pdfjadetex
> not working in the latest release.

Well, I honestly wish I could provide insight on that specific
problem, but can't. Unfortunately, in my experience with Internet
discussions, it seems that instead of practical solutions to acute
problems, you instead often get just a bunch of opinionated
pronouncements from someone like me.

   --Mike Smith

-- 
Michael Smith          mailto:smith@xml-doc.org
XML-DOC                http://www.xml-doc.org/

Re: Where, what and how - The future of DocBook

[Jorge Godoy]

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

On Tue, 5 Dec 2000, pto@sslug.dk wrote:

> Agree. Can we get MANY people to use the tools?

What tools? DocBook XML + DSSSL + DSSSL processing tools OR DocBook
XML + XSL Stylesheets + XSL/XML able tools? 

I'm using the first solution mixed with both SGML and XML versions of
DocBook. All of Conectiva's documents (we're beggining with technical
stuff) are migrating to DocBook. Our books and booklets are being
written in DocBook.


As a big documentation project, LDP is also using DocBook. We've
implemented it and already have several documents marked accordingly
to DocBook DTD. 

> How do we get the tools working?
> - Which tools should the ordinary person download?
> - How are they installed?
> - Where is the first "lets try it" - example
> - Where is the tutorials?
> - Where is the full documentation?
> - Can we get standard Linux/*BSD distributions
>   to carry the tools?
> 
> These the the *KEY* questions to answer in the best
> possible way. I am sorry to say that I find it hard to
> find it.

OK. Try taking a look at my mess: http://bazar.conectiva.com.br/~godoy 
If you install the packages available there, you can ignore the
'tetex' ones (but make sure that you have it installed and in a
relatively new version).

I'm trying to gather together information about several things as I
need them (or need to explain them to somebody). I'm sorry but there
are some things in Portuguese and others in English. 


For the "full" documentation, you can try http://docbook.org --- and
buy the O'Reilly book; it's very good!


Standard Linux distributions such as Conectiva, Mandrake, Red Hat,
Debian, SuSE already have packages for DocBook usage.


>> James Clark's SP.
> 
> URL - again, download?, install?, howto? + full docs.

I'd suggest using OpenSP. 

http://openjade.sourceforge.net

> Who is making what at the moment for DocBook?

Development on DocBook or DocBook usage?

> Eg. IMT-2000 standardization (UMTS) - check
> http://www.3gpp.org -> all the work is Word-files.
> 
> I care a lot. I find that Word is eating WAY to much of
> the areas, where DocBook could have been cool. I think
> Word is preferred for many companies today - many do
> not consider DocBook - that is a shame - we can all
> agree on that!

Speak to them about information recuperability and for how long they
can have this same information available. What if they need to recover
some client information or document of a product that was written 5
years ago. Is Word able to do that? 

I confess I don't use Word for several years now (5, IIRC). I was a
Word heavy user, then I switched to LaTeX and now I'm on DocBook SGML
/ XML. 

With LaTeX or DocBook I'm sure that my document will look the same on
every machine I'm working. With Word I wasn't. 


> We have to IMHO!

In some aspects, IMHO, we have already done. 



See you,
-- 
Godoy. <godoy@conectiva.com>

Departamento de Publicações       Conectiva S.A.
Publishing Department             Conectiva Inc.

Re: Where, what and how - The future of DocBook

[Norman Walsh]

| Fine - which tools are available for writing
| SGML/DocBook on Linux+xBSD or Windows?

The future is XML, not SGML.

| - Emacs and alike tools?

Naturally.

| - Any WYSIWYG editors?

That said, for Windows there are lots of XML editing tools coming
online. For production environments, I would recommend Arbortext's
Epic (disclaimer: I used to work for them). SoftQuad's XMetaL is less
expensive.

| - Any *fast* syntax verification system

James Clark's SP.

| - and what is being made in general

What is being made of what in general?

| Many companies don't accept DocBook - why?

Many companies do. Bug ones. With lots of documentation: Sun, HP,
Novell, etc. Who doesn't accept it (and why do you care that they
don't?)

| Can't we do better???

I'm sure we can.

| What is the future for SGML/DocBook versus XML/DocBook
| - again also regarding tools, the work efford going on
| at the moment etc.

XML is the future. But since XML is SGML, there's no loss here. You
can continue to use your favorite SGML tools. But I don't expect any
more SGML tools to be written. Ever.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com> | We dance around in a ring and suppose,
http://nwalsh.com/            | but the Secret sits in the middle and
                              | knows.--Robert Frost

RE: Where, what and how - The future of DocBook

[Pfaffner, Peter]

Hi all,
I'm new to this discussion list and not sure, if this is the right way to
reply to a topic (sorry if I'm wrong).

Peter Toft brought up an interesting Question:
>>>Many companies don't accept DocBook - why?
>>>Can't we do better???

I'm responsible for all kinds of technical standards for 12 months now. One
of them is documentation. Actually I decided to switch from MsWord ;-) to
FrameMaker+SGML for Windows and have to choose/create a company-DTD. To make
a long story short, I decided not to use DocBook as delivered.

Why?
Well, at first, our writers are not used to SGML/XML at all, or native SGML
authoring tools (thats the reason for an expensive WYSIWYG tool like
FM+SGML). And it is essential for a broad acceptance of the paradigm change
to make the switch as smooth as possible. Try to replace the good old
typewriter of your grandpa by a computer, and you know what I am talking
about :-). Microsoft customers are used to menus, choices and WYSIWYG (and
I'm too in the meantime). I've worked with IBMs DCF/GML for almost 10 years
being tired to stare at tagged plaintext to figure out, how it might look in
print.
I installed the DocBook 3.0 EDD(DTD) for FrameMaker and tested it. To be
frank, the content model (take Element Para for example) is overwhelming.
The naming conventions for elements are not consistent, so that related
elements are not near to each other in the (alphabetically sorted) valid
element list. The mixture of elements for articles, reference pages and
books in one content model makes the whole thing sort of clumsy and I guess,
hard to maintain too.
Looking forward to DocBook 5.0 (XML?), it may get worse, because XML doesn't
support SGMLs Include/Exclude.

My personel recommendation is:
split the DocBook-Standard into smaller one's with a common subset of
elements and attributes. Wrap similar elements (all list types) in higher
level structures (for example "Lists"), which can be unwrapped by XSLT, if
necessary.

What I will do instead?
I'm going to write a new, simplified and heavily reduced XML-DTD (hey, what
are nights and weekends for ;-) based on DocBook V4.1 and IBMIDDOC trying to
be as  DocBook conformant as possible.

Suggestions and comments are appreciated.



-----Original Message-----
From: docbook-tools-discuss-owner@sources.redhat.com
[ mailto:docbook-tools-discuss-owner@sources.redhat.com]On Behalf Of
Peter Toft
Sent: Monday, December 04, 2000 12:07 PM
To: docbook-tools-discuss@sourceware.cygnus.com
Subject: Where, what and how - The future of DocBook

RE: Where, what and how - The future of DocBook

[Peter Ring]

You should have a look at < http://www.nwalsh.com/docbook/simple/index.html >.


If you want some inspiration for modularization, you should look at the way
XHTML is being modularized, < http://www.w3.org/TR/xhtml-modularization/ >.

IMHO, the real trouble starts when you do the applications to support your
modular DTD. Norman Walsh' modular DSSSL and XSLT stylesheets
< http://www.nwalsh.com/docbook/dsssl/index.html > might be an inspiration. If
you find out how to implement this for an FrameMaker+SGML EDD, I'd very much
like to know!


kind regards,
Peter Ring

-----Original Message-----
From: Pfaffner, Peter [ mailto:PP0099@entitec.de ]
Sent: 5. december 2000 16:27
To: DocBook forum (E-mail 2)
Subject: RE: Where, what and how - The future of DocBook


Hi all,
I'm new to this discussion list and not sure, if this is the right way to
reply to a topic (sorry if I'm wrong).

Peter Toft brought up an interesting Question:
>>>Many companies don't accept DocBook - why?
>>>Can't we do better???

I'm responsible for all kinds of technical standards for 12 months now. One
of them is documentation. Actually I decided to switch from MsWord ;-) to
FrameMaker+SGML for Windows and have to choose/create a company-DTD. To make
a long story short, I decided not to use DocBook as delivered.

Why?
Well, at first, our writers are not used to SGML/XML at all, or native SGML
authoring tools (thats the reason for an expensive WYSIWYG tool like
FM+SGML). And it is essential for a broad acceptance of the paradigm change
to make the switch as smooth as possible. Try to replace the good old
typewriter of your grandpa by a computer, and you know what I am talking
about :-). Microsoft customers are used to menus, choices and WYSIWYG (and
I'm too in the meantime). I've worked with IBMs DCF/GML for almost 10 years
being tired to stare at tagged plaintext to figure out, how it might look in
print.
I installed the DocBook 3.0 EDD(DTD) for FrameMaker and tested it. To be
frank, the content model (take Element Para for example) is overwhelming.
The naming conventions for elements are not consistent, so that related
elements are not near to each other in the (alphabetically sorted) valid
element list. The mixture of elements for articles, reference pages and
books in one content model makes the whole thing sort of clumsy and I guess,
hard to maintain too.
Looking forward to DocBook 5.0 (XML?), it may get worse, because XML doesn't
support SGMLs Include/Exclude.

My personel recommendation is:
split the DocBook-Standard into smaller one's with a common subset of
elements and attributes. Wrap similar elements (all list types) in higher
level structures (for example "Lists"), which can be unwrapped by XSLT, if
necessary.

What I will do instead?
I'm going to write a new, simplified and heavily reduced XML-DTD (hey, what
are nights and weekends for ;-) based on DocBook V4.1 and IBMIDDOC trying to
be as  DocBook conformant as possible.

Suggestions and comments are appreciated.



-----Original Message-----
From: docbook-tools-discuss-owner@sources.redhat.com
[ mailto:docbook-tools-discuss-owner@sources.redhat.com]On Behalf Of
Peter Toft
Sent: Monday, December 04, 2000 12:07 PM
To: docbook-tools-discuss@sourceware.cygnus.com
Subject: Where, what and how - The future of DocBook

Re: Where, what and how - The future of DocBook

[Alan W. Irwin]

Mike, I was reacting against those who implied DocBook was so difficult that
you absolutely required sophisticated tools to deal with it.  Also, you
have, IMO a weak argument about validation since it actually doesn't take
very long to do it on a modern PC independently of the editing process if
you do editing in one window and validation in another. My particular
project had a variety of tags, but the vast majority of them had quite
repetitive patterns so a working example was always nearby in the document.
Thus, I rarely (about 4 times in the whole project) had a validation error.
So things went really fast for the simple method I chose. That is an
important point I hope we can agree on; DocBook ain't difficult and doesn't
absolutely *require* sophisticated tools.

That said, you have been a good advocate for emacs/psgml (and so was my
partner in the project) so I will probably try it next time, but I don't
regret for a moment doing my first DocBook project this simple and
straightforward way. I seem to learn the best if I solve problems with
low-end tools to start, and then move on up to more sophisticated tools
later on.  YMMV, of course.

This has been an interesting discussion about methods and perhaps even
valuable as well, but I sure wish I could get as quick a response on this
list to the practical problem of Cygnus pdfjadetex not working in the
latest release.

Alan

email: irwin@beluga.phys.uvic.ca
phone: 250-727-2902	FAX: 250-721-7715
snail-mail:
Dr. Alan W. Irwin
Department of Physics and Astronomy,
University of Victoria, P.O. Box 3055,
Victoria, British Columbia, Canada, V8W 3P6 
__________________________

Linux-powered astrophysics
__________________________

On 5 Dec 2000, Michael Smith wrote:

> Alan W. Irwin <irwin@beluga.phys.uvic.ca> writes:
> 
> > I am a member of a two-man team that converted a largish piece (more
> > than 100 pages) of technical documentation from latexinfo to DocBook
> > 4.1 XML. [...]
> >
> > Since the conversion was completed I have been entering lots of
> > extra content with an ordinary editor (jed). I understand there is a
> > great DocBook interface available with emacs, but I haven't bothered
> > with it yet because it is not really needed. From my experience I
> > would assert you don't need any special tool to edit and improve
> > documentation written in DocBook. The tags that are ordinarily used
> > are easy to memorize. Of course, it probably helps that I am a good
> > touch typist. If you don't have that skill I guess you need to find
> > some tool that gives you WYSIWYG. But it wasn't necessary in my
> > case, and I suspect that is true for most documenters.
> 
> Yipes -- all due respect, but I think your suspicion may be way off.
> 
> The big advantage of an editor like Emacs/psgml is that it takes much
> of the guesswork out of document authoring. Validating editors by
> design make it hard to produce invalid documents. Using a validating
> editor, you really have to go out of your way to make something that
> won't validate. Only way you can do it is to type tags in manually --
> which you should never need to do with a good XML editing app.
> 
> Sure, jed's great (so's Vim -- better syntax highlighting), but if
> you've never used a validating editor like Emacs/psgml, you don't know
> what you're missing.
> 
> I read a thread on the LDP list in which a writer said that one
> advantage of LinuxDoc was its short element names. It baffled me why
> he would care how long the names were -- until I realized he was
> probably typing them by hand using a regular text editor.
> 
> Once I realized that, I was baffled as to why -- when Emacs/psgml is
> free, great, and so widely used -- why any skilled Linux user would
> rely on a regular (non-SGML-validating) editor to work with XML/SGML.
> 
> First of all, it ain't quicker -- don't care how fast you can type.
> And although it's great to memorize as much of DocBook as you can, I
> wonder what kind of agreement you'd get on what tags are "ordinarily
> used". I think that depends very much on what you're documenting. 
> 
> Confronted with DocBook's 375 elements (including 100+ "inline"
> elements that can occur in paragraphs) and 100+ attributes, I doubt
> that "most documentors" would find a validating editor uneccessary.
> 
> Most of the DocBook users I know (and I include myself) are not so
> familiar with the DTD that we can always judge with confidence what
> elements and attributes are -valid/required- where -- and why bother
> when you've got a DTD-aware validating editor to tell you that?
> 
> In fact, one of the main concerns I hear from SGML/XML authors --
> especially new ones -- is that their editing tools just aren't smart
> enough, and don't go far enough in simplifying the editing process.
> 
> No, I wouldn't suggest to anyone that they author DocBook docs using
> jed or any other non-validating editor -- unless they've got a lot of
> extra time on their hands, really enjoy typing, and really like the
> process of running documents through a parser, post-authoring, and
> fixing them manually to get them to validate.
> 
>   -- Mike Smith
> 
> -- 
> Michael Smith          mailto:smith@xml-doc.org
> XML-DOC                http://www.xml-doc.org/
> 
> 
> 
> 

Re: Where, what and how - The future of DocBook

[Alan W. Irwin]

I am a member of a two-man team that converted a largish piece (more than
100 pages) of technical documentation from latexinfo to DocBook 4.1 XML.
Fortunately, my partner is a real smart cookie so I let him handle most of
the technical end.  I have concentrated on editing the syntax changes with
considerable help from him on doing the routine part of it with scripts.

Since the conversion was completed I have been entering lots of extra
content with an ordinary editor (jed).  I understand there is a great
DocBook interface available with emacs, but I haven't bothered with it yet
because it is not really needed. From my experience I would assert you don't
need any special tool to edit and improve documentation written in DocBook.
The tags that are ordinarily used are easy to memorize.  Of course, it
probably helps that I am a good touch typist. If you don't have that skill I
guess you need to find some tool that gives you WYSIWYG.  But it wasn't
necessary in my case, and I suspect that is true for most documenters.

To move away from this useful but still rather generalized discussion, the
only real concern I have about DocBook at the moment is getting glitch-free
builds of our documentation with Cygnus DocBook 4.1 XML on Redhat 6.2
systems.... ;-)

The major glitch for us is the pdfjadetex command does not work in the
slightest (see my previous postings). I am confident that problem is such a
glaring error with such a simple demonstration that it will be rapidly
solved.  We have no such glitches on our Debian DocBook 4.1 XML system for
building our documentation so it provides a nice comparison to help sort out
problems in the recent 4.1 XML Cygnus version of DocBook.

Alan

email: irwin@beluga.phys.uvic.ca
phone: 250-727-2902	FAX: 250-721-7715
snail-mail:
Dr. Alan W. Irwin
Department of Physics and Astronomy,
University of Victoria, P.O. Box 3055,
Victoria, British Columbia, Canada, V8W 3P6 
__________________________

Linux-powered astrophysics
__________________________

Re: Where, what and how - The future of DocBook

[Hugo.van.der.Kooij]

On 7 Dec 2000, Gregory Leblanc wrote:

> We use just straight Jade, as the db2 scripts weren't very portable, and
> because we NEED good PS/PDF output.  The only thing that we're still
> working on is good text support.

I've been using the sgmltools fo a while. Recently I upgraded my system to
Red Hat Linux 7.0 and added sgmltools-lite to it.

sgmltools-lite has the ability to use w3m which support tables. So you can
get a reasonable good ascii output.

Hugo.

-- 
Hugo van der Kooij; Oranje Nassaustraat 16; 3155 VJ  Maasland
hvdkooij@caiw.nl	http://home.kabelfoon.nl/~hvdkooij/
--------------------------------------------------------------
This message has not been checked and may contain harmfull content.

Re: Where, what and how - The future of DocBook

[madhu]

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

Hello,

On Wed, 06 Dec 2000, Eric Bischoff wrote:

> 
> and a source of documentation: the crash-course to DocBook at
> 
> 	http://www.caldera.de/~eric/crash-course
> 
> (this guide will be integrated to Debian soon, BTW).
> 
> -- 
> Éric Bischoff                                  mailto:e.bischoff@noos.fr

i get a 403 error with this url 
and it tells me :
Forbidden

You don't have permission to access /~eric/crash-course/ on this server.


regards

have fun but do take care


maddy

Re: Where, what and how - The future of DocBook

[Michael Smith]

madhu <bmadi_1@yahoo.com> writes:

> On Wed, 06 Dec 2000, Eric Bischoff wrote:
> 
> > and a source of documentation: the crash-course to DocBook at
> > 
> > 	http://www.caldera.de/~eric/crash-course
> 
> i get a 403 error with this url and it tells me : Forbidden
> You don't have permission to access /~eric/crash-course/ on this
> server.

http://www.caldera.de/~eric/crash-course/HTML/index.html


-- 
Michael Smith          mailto:smith@xml-doc.org
XML-Doc                http://www.xml-doc.org/

Re: Where, what and how - The future of DocBook

[madhu]

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

Hello,

On Wed, 06 Dec 2000, Eric Bischoff wrote:

> 
> and a source of documentation: the crash-course to DocBook at
> 
> 	http://www.caldera.de/~eric/crash-course
> 
> (this guide will be integrated to Debian soon, BTW).
> 
> -- 
> Éric Bischoff                                  mailto:e.bischoff@noos.fr

i get a 403 error with this url 
and it tells me :
Forbidden

You don't have permission to access /~eric/crash-course/ on this server.


regards

have fun but do take care


maddy

Re: Where, what and how - The future of DocBook

[Hugo.van.der.Kooij]

On 7 Dec 2000, Gregory Leblanc wrote:

> We use just straight Jade, as the db2 scripts weren't very portable, and
> because we NEED good PS/PDF output.  The only thing that we're still
> working on is good text support.

I've been using the sgmltools fo a while. Recently I upgraded my system to
Red Hat Linux 7.0 and added sgmltools-lite to it.

sgmltools-lite has the ability to use w3m which support tables. So you can
get a reasonable good ascii output.

Hugo.

-- 
Hugo van der Kooij; Oranje Nassaustraat 16; 3155 VJ  Maasland
hvdkooij@caiw.nl	http://home.kabelfoon.nl/~hvdkooij/
--------------------------------------------------------------
This message has not been checked and may contain harmfull content.

Re: Where, what and how - The future of DocBook

[Craig Boone]

Gregory Leblanc wrote:
> 
> 
> Take a look at the LDP Authors Guide
> http://www.LinuxDoc.org/LDP/LDP-Author-Guide/
> It's got a great deal of information on what the LDP is using.  I'm
> actually working on a jade wrapper using make rather than the stuff that
> the docbook tools project has done, as this is exactly what make is
> designed for.  I hope to have something worth showing off early next
> year.
> 
>     Greg


Thanks for the feedback.  I really appreciate it.

C-

-- 
Craig A. Boone          craig@estinc.com
Technical Writer        Enhanced Software Technologies, Inc.
Ph:  602.470.1115       Fax:  602.470.1116
                        www.estinc.com

After the game, the king and pawn go into the same box. --Italian
Proverb

Loyalty to a petrified opinion never yet broke a chain or freed a human
soul.
--Mark Twain

Re: Where, what and how - The future of DocBook

[Gregory Leblanc]

> Gregory Leblanc wrote:
> 
> > I've gotten around this the easy way, I don't use pdfjadetex.  Instead,
> > I use a tool called htmldoc, which convers from HTML to PS/PDF, and does
> > a VERY nice job at it.  The only thing that's missing is that it doesn't
> > convert the external (href) hyperlinks to something useful along the
> > way.  I can do this with jade, but jade is slow.
> > 
> >     Greg
> 
> Is htmldoc something that you created, or is it something that's
> available for download?  I can't seem to get any of the pdf/ps


I guess this is what I get for not posting a
URL.  :-)  http://www.easysw.com/htmldoc/  htmldoc is GPL, so use it how
you like.


> conversions to occur properly with the DocBook tools that I have.  I'm
> using the db2pdf and db2ps scripts and all they seem to do is explode
> and spew latex errors everywhere.  I can write picture-perfect sgml and
> it makes lovely html conversions, but it doesn't do me much good if I
> can't get it printed. 


We use just straight Jade, as the db2 scripts weren't very portable, and
because we NEED good PS/PDF output.  The only thing that we're still
working on is good text support.


> I've been monitoring this list and watching all of the "Future of
> DocBook" threads and I gotta say it's a great project and I'd love to be
> able to set it as a standard to create all of my documentation. 
> However, I just can't seem to get a dependable set of tools and solidly
> implement them.  Suggestions?


Take a look at the LDP Authors Guide
http://www.LinuxDoc.org/LDP/LDP-Author-Guide/
It's got a great deal of information on what the LDP is using.  I'm
actually working on a jade wrapper using make rather than the stuff that
the docbook tools project has done, as this is exactly what make is
designed for.  I hope to have something worth showing off early next
year.

    Greg

Re: Where, what and how - The future of DocBook

[Craig Boone]

Gregory Leblanc wrote:

> I've gotten around this the easy way, I don't use pdfjadetex.  Instead,
> I use a tool called htmldoc, which convers from HTML to PS/PDF, and does
> a VERY nice job at it.  The only thing that's missing is that it doesn't
> convert the external (href) hyperlinks to something useful along the
> way.  I can do this with jade, but jade is slow.
> 
>     Greg

Is htmldoc something that you created, or is it something that's
available for download?  I can't seem to get any of the pdf/ps
conversions to occur properly with the DocBook tools that I have.  I'm
using the db2pdf and db2ps scripts and all they seem to do is explode
and spew latex errors everywhere.  I can write picture-perfect sgml and
it makes lovely html conversions, but it doesn't do me much good if I
can't get it printed. 

I've been monitoring this list and watching all of the "Future of
DocBook" threads and I gotta say it's a great project and I'd love to be
able to set it as a standard to create all of my documentation. 
However, I just can't seem to get a dependable set of tools and solidly
implement them.  Suggestions?

-- 
Craig A. Boone          craig@estinc.com
Technical Writer        Enhanced Software Technologies, Inc.
Ph:  602.470.1115       Fax:  602.470.1116
                        www.estinc.com

After the game, the king and pawn go into the same box. --Italian
Proverb

Loyalty to a petrified opinion never yet broke a chain or freed a human
soul.
--Mark Twain

Re: Where, what and how - The future of DocBook

[Gregory Leblanc]

> That said, you have been a good advocate for emacs/psgml (and so was my
> partner in the project) so I will probably try it next time, but I don't
> regret for a moment doing my first DocBook project this simple and
> straightforward way. I seem to learn the best if I solve problems with
> low-end tools to start, and then move on up to more sophisticated tools
> later on.  YMMV, of course.


I dove into psgml when I first started writing, and it was a really nice
learning tool, especially combined with the templates that the GNOME Doc
Project has.  I've since become one of the most knowledgeable docbook
people actively involved in that project.

> This has been an interesting discussion about methods and perhaps even
> valuable as well, but I sure wish I could get as quick a response on this
> list to the practical problem of Cygnus pdfjadetex not working in the
> latest release.


I've gotten around this the easy way, I don't use pdfjadetex.  Instead,
I use a tool called htmldoc, which convers from HTML to PS/PDF, and does
a VERY nice job at it.  The only thing that's missing is that it doesn't
convert the external (href) hyperlinks to something useful along the
way.  I can do this with jade, but jade is slow.

    Greg

Re: Where, what and how - The future of DocBook

[Eric Bischoff]

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

Mark Johnson wrote:
> 
> Eric Bischoff wrote:
> 
> > Michael Wiedmann wrote:
> > >
> > > I'm editing my XML DocBook files using PSGML and didn't run into
> > > any problems up to now.
> >
> > Did you have to do something in special that would be relevant to
> > include in the doc at this place?
> 
> You might want to add that validation requires the XML declaration (xml.dcl
> or xml.decl) rather than docbook.dcl.

Okay. I now include this file in sgml-common package.

> In your .emacs you may have something like:
> 
>     (setq sgml-declaration "/usr/lib/sgml/declaration/docbook.dcl")
> 
> For XML I tried the following, but for some reason it doesn't work:
> 
>     (setq sgml-xml-declaration "/usr/lib/sgml/declaration/xml.dcl")
> 
> So I use:
> 
>         (setq sgml-declaration "/usr/lib/sgml/declaration/xml.dcl")
> 
> The paths are probably different on a redhat machine.
> 
> ...my $0.02

I will try to incorporate those lines to the psgml package or to the
doc. Thanks for your two cents ;-).

-- 
+----------------------------------------------------------------------+
| Éric Bischoff                              mailto:e.bischoff@noos.fr |
+----------------------------------------------------------------------+

Re: Where, what and how - The future of DocBook

[Mark Johnson]

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

Eric Bischoff wrote:

> Michael Wiedmann wrote:
> >
> > I'm editing my XML DocBook files using PSGML and didn't run into
> > any problems up to now.
>
> Did you have to do something in special that would be relevant to
> include in the doc at this place?

You might want to add that validation requires the XML declaration (xml.dcl
or xml.decl) rather than docbook.dcl.

In your .emacs you may have something like:

    (setq sgml-declaration "/usr/lib/sgml/declaration/docbook.dcl")

For XML I tried the following, but for some reason it doesn't work:

    (setq sgml-xml-declaration "/usr/lib/sgml/declaration/xml.dcl")

So I use:

        (setq sgml-declaration "/usr/lib/sgml/declaration/xml.dcl")

The paths are probably different on a redhat machine.

...my $0.02


Mark


>
>
> > > (this guide will be integrated to Debian soon, BTW).
> >
> > That's good news!
>
> :-)
>
> --
> Éric Bischoff                                  mailto:e.bischoff@noos.fr
> -- Support your government, give Echelon/Carnivore something to parse --
> AMTAS ATMD ATSC Abdullah Allah  communist CIA DD2-N DISA DoD GRU Gregori
> Irak  Iran KGB  Kurdish LSD  NATO NSTD  Natasha  ORD RTEM  Russia  STRAP
> Saddam Hussein  TSP  Yugoslavia   attack  bank  bomb  classfield  cocain
> compromise defense  democracy  destroy  destruct  detonator  directorate
> elections enforce extasy force  foreign embassy government grass hashish
> heroin   illegal  information   international  military systems  missile
> million dollars   nuclear  policital   pot  power   presidental  project
> restricted data  revolution  rule the world sensitive  smuggle spy steal
> system  takeover  terrorist  top-secret  warmod  warrior-T  weapon  weed
> ------------------------------------------------------------------------

Re: Where, what and how - The future of DocBook

[Eric Bischoff]

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

Michael Wiedmann wrote:
> 
> Eric Bischoff wrote:
> ...
> > and a source of documentation: the crash-course to DocBook at
> >
> >         http://www.caldera.de/~eric/crash-course
> 
> Forbidden :-(
> but http://www.caldera.de/~eric/ works :-)


Sorry, I should have said

	http://www.caldera.de/~eric/crash-course/HTML/index.html

> One remark/question:
> In "App. B. Emacs PSGML mode tips" your write
> 
> "Note: PSGML mode is for SGML DocBook. It does not support
>  XML DocBook."
> 
> Is this really true?

Hmmm, someone else already pointed this out. I thought I removed it. On
my TODO list.

> I'm editing my XML DocBook files using PSGML and didn't run into
> any problems up to now.

Did you have to do something in special that would be relevant to
include in the doc at this place.

> > (this guide will be integrated to Debian soon, BTW).
> 
> That's good news!

:-)

-- 
Éric Bischoff                                  mailto:e.bischoff@noos.fr
-- Support your government, give Echelon/Carnivore something to parse --
AMTAS ATMD ATSC Abdullah Allah  communist CIA DD2-N DISA DoD GRU Gregori
Irak  Iran KGB  Kurdish LSD  NATO NSTD  Natasha  ORD RTEM  Russia  STRAP
Saddam Hussein  TSP  Yugoslavia   attack  bank  bomb  classfield  cocain
compromise defense  democracy  destroy  destruct  detonator  directorate
elections enforce extasy force  foreign embassy government grass hashish
heroin   illegal  information   international  military systems  missile
million dollars   nuclear  policital   pot  power   presidental  project
restricted data  revolution  rule the world sensitive  smuggle spy steal
system  takeover  terrorist  top-secret  warmod  warrior-T  weapon  weed
------------------------------------------------------------------------

Re: Where, what and how - The future of DocBook

[Michael Wiedmann]

Eric Bischoff wrote:
... 
> and a source of documentation: the crash-course to DocBook at
> 
>         http://www.caldera.de/~eric/crash-course

Forbidden :-(
but http://www.caldera.de/~eric/ works :-)

One remark/question:
In "App. B. Emacs PSGML mode tips" your write

"Note: PSGML mode is for SGML DocBook. It does not support
 XML DocBook."

Is this really true? 
I'm editing my XML DocBook files using PSGML and didn't run into 
any problems up to now.

> (this guide will be integrated to Debian soon, BTW).

That's good news!

Michael
-- 
office:  michael.wiedmann@detewe.de
private: mw@miwie.in-berlin.de                 http://www.miwie.org/
         mw@miwie.org                          http://wap.miwie.org/

Re: Where, what and how - The future of DocBook

[Eric Bischoff]

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

Sorry if I'm repeating myself, but:

Did someone ever succeed in converting a Korean/Japanese/Chinese DocBook
file into PDF or PostScript? I need help on this.

-- 
Éric Bischoff                                  mailto:e.bischoff@noos.fr
-- Support your government, give Echelon/Carnivore something to parse --
AMTAS ATMD ATSC Abdullah Allah  communist CIA DD2-N DISA DoD GRU Gregori
Irak  Iran KGB  Kurdish LSD  NATO NSTD  Natasha  ORD RTEM  Russia  STRAP
Saddam Hussein  TSP  Yugoslavia   attack  bank  bomb  classfield  cocain
compromise defense  democracy  destroy  destruct  detonator  directorate
elections enforce extasy force  foreign embassy government grass hashish
heroin   illegal  information   international  military systems  missile
million dollars   nuclear  policital   pot  power   presidental  project
restricted data  revolution  rule the world sensitive  smuggle spy steal
system  takeover  terrorist  top-secret  warmod  warrior-T  weapon  weed
------------------------------------------------------------------------

Re: Where, what and how - The future of DocBook

[Eric Bischoff]

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

> For the "full" documentation, you can try http://docbook.org --- and
> buy the O'Reilly book; it's very good!
> 
> Standard Linux distributions such as Conectiva, Mandrake, Red Hat,
> Debian, SuSE already have packages for DocBook usage.


I'd like to remind another source of packages: The "docbook-tools" at 

	ftp://sourceware.cygnus.com/pub/docbook-tools/new-trials/

and a source of documentation: the crash-course to DocBook at

	http://www.caldera.de/~eric/crash-course

(this guide will be integrated to Debian soon, BTW).

-- 
Éric Bischoff                                  mailto:e.bischoff@noos.fr
-- Support your government, give Echelon/Carnivore something to parse --
AMTAS ATMD ATSC Abdullah Allah  communist CIA DD2-N DISA DoD GRU Gregori
Irak  Iran KGB  Kurdish LSD  NATO NSTD  Natasha  ORD RTEM  Russia  STRAP
Saddam Hussein  TSP  Yugoslavia   attack  bank  bomb  classfield  cocain
compromise defense  democracy  destroy  destruct  detonator  directorate
elections enforce extasy force  foreign embassy government grass hashish
heroin   illegal  information   international  military systems  missile
million dollars   nuclear  policital   pot  power   presidental  project
restricted data  revolution  rule the world sensitive  smuggle spy steal
system  takeover  terrorist  top-secret  warmod  warrior-T  weapon  weed
------------------------------------------------------------------------

Re: Where, what and how - The future of DocBook

[Michael Smith]

Alan, you wrote:

> Mike, I was reacting against those who implied DocBook was so
> difficult that you absolutely required sophisticated tools to deal
> with it.

Yes, sorry if I came across a too emphatically. I definitely concur
with you there -- no sophisticated (commercial?) tools are required.
Using DocBook is never more nor less complex than your needs -- that
is, what you need to encode in your document instances.

And regardless of complexity, my response to those (not you of course)
who question using DocBook for hardware/software documentation is,
-Please show me an alternative-.

I guess someone who wanted to could re-invent the wheel and come up
with a kind of subset of DocBook. But Norm Walsh and the others
guiding DocBook have already provided DocBook with a customization
layer designed to facilitate subsetting and/or enhancements. Sure,
it's not trivial to design/configure a DocBook subset -- but it's a
hell of a lot easier than with any other DTD I've ever used.

> Also, you have, IMO a weak argument about validation since it
> actually doesn't take very long to do it on a modern PC
> independently of the editing process if you do editing in one window
> and validation in another.

OK, yes maybe I overstated that. But to put things in perspective: you
mentioned that you were working on a hundred-page document.

Not to downplay the work I'm sure you put into marking up that
document, but for a lot of the doc folks I know, a hundred page
document is a walk in the park -- these people (not me, thank god
almighty) are working on things like huge "butterfly" manuals that run
to so many pages no one bothers to count them. Awful stuff.

I would not want to work on documents of that length without a
vailidating editor. Actually, wouldn't want to work on that kind of
stuff at all myself -- but I guess somebody's got to do it.

> [...] I rarely (about 4 times in the whole project) had a validation
> error. So things went really fast for the simple method I chose.
> That is an important point I hope we can agree on; DocBook ain't
> difficult and doesn't absolutely *require* sophisticated tools.

You're right of course.

> That said, you have been a good advocate for emacs/psgml (and so was
> my partner in the project) so I will probably try it next time

Very glad to hear that.

If after using psgml, you or anyone on the list has ideas on improving
psgml, I want to encourage you to help make it better -- because
Lennart Staflin has, yahoo!, recently moved the psgml source to
Sourceforge, opened it to collaborative development and set up mailing
lists for discussions along those lines. Take a look:

  http://sourceforge.net/projects/psgml

> but I don't regret for a moment doing my first DocBook project
> this simple and straightforward way. I seem to learn the best if I
> solve problems with low-end tools to start, and then move on up to
> more sophisticated tools later on. YMMV, of course.

Again, you're right -- no one can take issue with that philosophy. 

> This has been an interesting discussion about methods and perhaps
> even valuable as well, but I sure wish I could get as quick a
> response on this list to the practical problem of Cygnus pdfjadetex
> not working in the latest release.

Well, I honestly wish I could provide insight on that specific
problem, but can't. Unfortunately, in my experience with Internet
discussions, it seems that instead of practical solutions to acute
problems, you instead often get just a bunch of opinionated
pronouncements from someone like me.

   --Mike Smith

-- 
Michael Smith          mailto:smith@xml-doc.org
XML-DOC                http://www.xml-doc.org/

Re: Where, what and how - The future of DocBook

[Alan W. Irwin]

Mike, I was reacting against those who implied DocBook was so difficult that
you absolutely required sophisticated tools to deal with it.  Also, you
have, IMO a weak argument about validation since it actually doesn't take
very long to do it on a modern PC independently of the editing process if
you do editing in one window and validation in another. My particular
project had a variety of tags, but the vast majority of them had quite
repetitive patterns so a working example was always nearby in the document.
Thus, I rarely (about 4 times in the whole project) had a validation error.
So things went really fast for the simple method I chose. That is an
important point I hope we can agree on; DocBook ain't difficult and doesn't
absolutely *require* sophisticated tools.

That said, you have been a good advocate for emacs/psgml (and so was my
partner in the project) so I will probably try it next time, but I don't
regret for a moment doing my first DocBook project this simple and
straightforward way. I seem to learn the best if I solve problems with
low-end tools to start, and then move on up to more sophisticated tools
later on.  YMMV, of course.

This has been an interesting discussion about methods and perhaps even
valuable as well, but I sure wish I could get as quick a response on this
list to the practical problem of Cygnus pdfjadetex not working in the
latest release.

Alan

email: irwin@beluga.phys.uvic.ca
phone: 250-727-2902	FAX: 250-721-7715
snail-mail:
Dr. Alan W. Irwin
Department of Physics and Astronomy,
University of Victoria, P.O. Box 3055,
Victoria, British Columbia, Canada, V8W 3P6 
__________________________

Linux-powered astrophysics
__________________________

On 5 Dec 2000, Michael Smith wrote:

> Alan W. Irwin <irwin@beluga.phys.uvic.ca> writes:
> 
> > I am a member of a two-man team that converted a largish piece (more
> > than 100 pages) of technical documentation from latexinfo to DocBook
> > 4.1 XML. [...]
> >
> > Since the conversion was completed I have been entering lots of
> > extra content with an ordinary editor (jed). I understand there is a
> > great DocBook interface available with emacs, but I haven't bothered
> > with it yet because it is not really needed. From my experience I
> > would assert you don't need any special tool to edit and improve
> > documentation written in DocBook. The tags that are ordinarily used
> > are easy to memorize. Of course, it probably helps that I am a good
> > touch typist. If you don't have that skill I guess you need to find
> > some tool that gives you WYSIWYG. But it wasn't necessary in my
> > case, and I suspect that is true for most documenters.
> 
> Yipes -- all due respect, but I think your suspicion may be way off.
> 
> The big advantage of an editor like Emacs/psgml is that it takes much
> of the guesswork out of document authoring. Validating editors by
> design make it hard to produce invalid documents. Using a validating
> editor, you really have to go out of your way to make something that
> won't validate. Only way you can do it is to type tags in manually --
> which you should never need to do with a good XML editing app.
> 
> Sure, jed's great (so's Vim -- better syntax highlighting), but if
> you've never used a validating editor like Emacs/psgml, you don't know
> what you're missing.
> 
> I read a thread on the LDP list in which a writer said that one
> advantage of LinuxDoc was its short element names. It baffled me why
> he would care how long the names were -- until I realized he was
> probably typing them by hand using a regular text editor.
> 
> Once I realized that, I was baffled as to why -- when Emacs/psgml is
> free, great, and so widely used -- why any skilled Linux user would
> rely on a regular (non-SGML-validating) editor to work with XML/SGML.
> 
> First of all, it ain't quicker -- don't care how fast you can type.
> And although it's great to memorize as much of DocBook as you can, I
> wonder what kind of agreement you'd get on what tags are "ordinarily
> used". I think that depends very much on what you're documenting. 
> 
> Confronted with DocBook's 375 elements (including 100+ "inline"
> elements that can occur in paragraphs) and 100+ attributes, I doubt
> that "most documentors" would find a validating editor uneccessary.
> 
> Most of the DocBook users I know (and I include myself) are not so
> familiar with the DTD that we can always judge with confidence what
> elements and attributes are -valid/required- where -- and why bother
> when you've got a DTD-aware validating editor to tell you that?
> 
> In fact, one of the main concerns I hear from SGML/XML authors --
> especially new ones -- is that their editing tools just aren't smart
> enough, and don't go far enough in simplifying the editing process.
> 
> No, I wouldn't suggest to anyone that they author DocBook docs using
> jed or any other non-validating editor -- unless they've got a lot of
> extra time on their hands, really enjoy typing, and really like the
> process of running documents through a parser, post-authoring, and
> fixing them manually to get them to validate.
> 
>   -- Mike Smith
> 
> -- 
> Michael Smith          mailto:smith@xml-doc.org
> XML-DOC                http://www.xml-doc.org/
> 
> 
> 
> 

Re: Where, what and how - The future of DocBook

[Michael Smith]

Alan W. Irwin <irwin@beluga.phys.uvic.ca> writes:

> I am a member of a two-man team that converted a largish piece (more
> than 100 pages) of technical documentation from latexinfo to DocBook
> 4.1 XML. [...]
>
> Since the conversion was completed I have been entering lots of
> extra content with an ordinary editor (jed). I understand there is a
> great DocBook interface available with emacs, but I haven't bothered
> with it yet because it is not really needed. From my experience I
> would assert you don't need any special tool to edit and improve
> documentation written in DocBook. The tags that are ordinarily used
> are easy to memorize. Of course, it probably helps that I am a good
> touch typist. If you don't have that skill I guess you need to find
> some tool that gives you WYSIWYG. But it wasn't necessary in my
> case, and I suspect that is true for most documenters.

Yipes -- all due respect, but I think your suspicion may be way off.

The big advantage of an editor like Emacs/psgml is that it takes much
of the guesswork out of document authoring. Validating editors by
design make it hard to produce invalid documents. Using a validating
editor, you really have to go out of your way to make something that
won't validate. Only way you can do it is to type tags in manually --
which you should never need to do with a good XML editing app.

Sure, jed's great (so's Vim -- better syntax highlighting), but if
you've never used a validating editor like Emacs/psgml, you don't know
what you're missing.

I read a thread on the LDP list in which a writer said that one
advantage of LinuxDoc was its short element names. It baffled me why
he would care how long the names were -- until I realized he was
probably typing them by hand using a regular text editor.

Once I realized that, I was baffled as to why -- when Emacs/psgml is
free, great, and so widely used -- why any skilled Linux user would
rely on a regular (non-SGML-validating) editor to work with XML/SGML.

First of all, it ain't quicker -- don't care how fast you can type.
And although it's great to memorize as much of DocBook as you can, I
wonder what kind of agreement you'd get on what tags are "ordinarily
used". I think that depends very much on what you're documenting. 

Confronted with DocBook's 375 elements (including 100+ "inline"
elements that can occur in paragraphs) and 100+ attributes, I doubt
that "most documentors" would find a validating editor uneccessary.

Most of the DocBook users I know (and I include myself) are not so
familiar with the DTD that we can always judge with confidence what
elements and attributes are -valid/required- where -- and why bother
when you've got a DTD-aware validating editor to tell you that?

In fact, one of the main concerns I hear from SGML/XML authors --
especially new ones -- is that their editing tools just aren't smart
enough, and don't go far enough in simplifying the editing process.

No, I wouldn't suggest to anyone that they author DocBook docs using
jed or any other non-validating editor -- unless they've got a lot of
extra time on their hands, really enjoy typing, and really like the
process of running documents through a parser, post-authoring, and
fixing them manually to get them to validate.

  -- Mike Smith

-- 
Michael Smith          mailto:smith@xml-doc.org
XML-DOC                http://www.xml-doc.org/

Re: Where, what and how - The future of DocBook

[Jorge Godoy]

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

On Tue, 5 Dec 2000, pto@sslug.dk wrote:

> Agree. Can we get MANY people to use the tools?

What tools? DocBook XML + DSSSL + DSSSL processing tools OR DocBook
XML + XSL Stylesheets + XSL/XML able tools? 

I'm using the first solution mixed with both SGML and XML versions of
DocBook. All of Conectiva's documents (we're beggining with technical
stuff) are migrating to DocBook. Our books and booklets are being
written in DocBook.


As a big documentation project, LDP is also using DocBook. We've
implemented it and already have several documents marked accordingly
to DocBook DTD. 

> How do we get the tools working?
> - Which tools should the ordinary person download?
> - How are they installed?
> - Where is the first "lets try it" - example
> - Where is the tutorials?
> - Where is the full documentation?
> - Can we get standard Linux/*BSD distributions
>   to carry the tools?
> 
> These the the *KEY* questions to answer in the best
> possible way. I am sorry to say that I find it hard to
> find it.

OK. Try taking a look at my mess: http://bazar.conectiva.com.br/~godoy 
If you install the packages available there, you can ignore the
'tetex' ones (but make sure that you have it installed and in a
relatively new version).

I'm trying to gather together information about several things as I
need them (or need to explain them to somebody). I'm sorry but there
are some things in Portuguese and others in English. 


For the "full" documentation, you can try http://docbook.org --- and
buy the O'Reilly book; it's very good!


Standard Linux distributions such as Conectiva, Mandrake, Red Hat,
Debian, SuSE already have packages for DocBook usage.


>> James Clark's SP.
> 
> URL - again, download?, install?, howto? + full docs.

I'd suggest using OpenSP. 

http://openjade.sourceforge.net

> Who is making what at the moment for DocBook?

Development on DocBook or DocBook usage?

> Eg. IMT-2000 standardization (UMTS) - check
> http://www.3gpp.org -> all the work is Word-files.
> 
> I care a lot. I find that Word is eating WAY to much of
> the areas, where DocBook could have been cool. I think
> Word is preferred for many companies today - many do
> not consider DocBook - that is a shame - we can all
> agree on that!

Speak to them about information recuperability and for how long they
can have this same information available. What if they need to recover
some client information or document of a product that was written 5
years ago. Is Word able to do that? 

I confess I don't use Word for several years now (5, IIRC). I was a
Word heavy user, then I switched to LaTeX and now I'm on DocBook SGML
/ XML. 

With LaTeX or DocBook I'm sure that my document will look the same on
every machine I'm working. With Word I wasn't. 


> We have to IMHO!

In some aspects, IMHO, we have already done. 



See you,
-- 
Godoy. <godoy@conectiva.com>

Departamento de Publicações       Conectiva S.A.
Publishing Department             Conectiva Inc.

Re: Where, what and how - The future of DocBook

[Alan W. Irwin]

I am a member of a two-man team that converted a largish piece (more than
100 pages) of technical documentation from latexinfo to DocBook 4.1 XML.
Fortunately, my partner is a real smart cookie so I let him handle most of
the technical end.  I have concentrated on editing the syntax changes with
considerable help from him on doing the routine part of it with scripts.

Since the conversion was completed I have been entering lots of extra
content with an ordinary editor (jed).  I understand there is a great
DocBook interface available with emacs, but I haven't bothered with it yet
because it is not really needed. From my experience I would assert you don't
need any special tool to edit and improve documentation written in DocBook.
The tags that are ordinarily used are easy to memorize.  Of course, it
probably helps that I am a good touch typist. If you don't have that skill I
guess you need to find some tool that gives you WYSIWYG.  But it wasn't
necessary in my case, and I suspect that is true for most documenters.

To move away from this useful but still rather generalized discussion, the
only real concern I have about DocBook at the moment is getting glitch-free
builds of our documentation with Cygnus DocBook 4.1 XML on Redhat 6.2
systems.... ;-)

The major glitch for us is the pdfjadetex command does not work in the
slightest (see my previous postings). I am confident that problem is such a
glaring error with such a simple demonstration that it will be rapidly
solved.  We have no such glitches on our Debian DocBook 4.1 XML system for
building our documentation so it provides a nice comparison to help sort out
problems in the recent 4.1 XML Cygnus version of DocBook.

Alan

email: irwin@beluga.phys.uvic.ca
phone: 250-727-2902	FAX: 250-721-7715
snail-mail:
Dr. Alan W. Irwin
Department of Physics and Astronomy,
University of Victoria, P.O. Box 3055,
Victoria, British Columbia, Canada, V8W 3P6 
__________________________

Linux-powered astrophysics
__________________________

Re: Where, what and how - The future of DocBook

[Peter Toft]

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

On 4 Dec 2000, Norman Walsh wrote:

> | Fine - which tools are available for writing
> | SGML/DocBook on Linux+xBSD or Windows?
>
> The future is XML, not SGML.

Agree. Can we get MANY people to use the tools?
How do we get the tools working?
- Which tools should the ordinary person download?
- How are they installed?
- Where is the first "lets try it" - example
- Where is the tutorials?
- Where is the full documentation?
- Can we get standard Linux/*BSD distributions
  to carry the tools?

These the the *KEY* questions to answer in the best
possible way. I am sorry to say that I find it hard to
find it.

>
> | - Emacs and alike tools?
>
> Naturally.

;-)))

>
> | - Any WYSIWYG editors?
>
> That said, for Windows there are lots of XML editing tools coming
> online. For production environments, I would recommend Arbortext's
> Epic (disclaimer: I used to work for them). SoftQuad's XMetaL is less
> expensive.
>
> | - Any *fast* syntax verification system
>
> James Clark's SP.

URL - again, download?, install?, howto? + full docs.

>
> | - and what is being made in general
>
> What is being made of what in general?

Who is making what at the moment for DocBook?

>
> | Many companies don't accept DocBook - why?
>
> Many companies do. Bug ones. With lots of documentation: Sun, HP,
> Novell, etc. Who doesn't accept it (and why do you care that they
> don't?)

Eg. IMT-2000 standardization (UMTS) - check
http://www.3gpp.org -> all the work is Word-files.

I care a lot. I find that Word is eating WAY to much of
the areas, where DocBook could have been cool. I think
Word is preferred for many companies today - many do
not consider DocBook - that is a shame - we can all
agree on that!




>
> | Can't we do better???
>
> I'm sure we can.

We have to IMHO!

>
> | What is the future for SGML/DocBook versus XML/DocBook
> | - again also regarding tools, the work efford going on
> | at the moment etc.
>
> XML is the future. But since XML is SGML, there's no loss here. You
> can continue to use your favorite SGML tools. But I don't expect any
> more SGML tools to be written. Ever.

Ok ;-))

-- 
Peter Toft, Ph.D. [pto@sslug.dk] http://www.sslug.dk/~pto

"You don't win a battle by asking, `Will we win?'
You win it by doing your best to win" - Richard M Stallman

LinuxKonference i København: http://LinuxForum.dk/

RE: Where, what and how - The future of DocBook

[Peter Ring]

You should have a look at < http://www.nwalsh.com/docbook/simple/index.html >.


If you want some inspiration for modularization, you should look at the way
XHTML is being modularized, < http://www.w3.org/TR/xhtml-modularization/ >.

IMHO, the real trouble starts when you do the applications to support your
modular DTD. Norman Walsh' modular DSSSL and XSLT stylesheets
< http://www.nwalsh.com/docbook/dsssl/index.html > might be an inspiration. If
you find out how to implement this for an FrameMaker+SGML EDD, I'd very much
like to know!


kind regards,
Peter Ring

-----Original Message-----
From: Pfaffner, Peter [ mailto:PP0099@entitec.de ]
Sent: 5. december 2000 16:27
To: DocBook forum (E-mail 2)
Subject: RE: Where, what and how - The future of DocBook


Hi all,
I'm new to this discussion list and not sure, if this is the right way to
reply to a topic (sorry if I'm wrong).

Peter Toft brought up an interesting Question:
>>>Many companies don't accept DocBook - why?
>>>Can't we do better???

I'm responsible for all kinds of technical standards for 12 months now. One
of them is documentation. Actually I decided to switch from MsWord ;-) to
FrameMaker+SGML for Windows and have to choose/create a company-DTD. To make
a long story short, I decided not to use DocBook as delivered.

Why?
Well, at first, our writers are not used to SGML/XML at all, or native SGML
authoring tools (thats the reason for an expensive WYSIWYG tool like
FM+SGML). And it is essential for a broad acceptance of the paradigm change
to make the switch as smooth as possible. Try to replace the good old
typewriter of your grandpa by a computer, and you know what I am talking
about :-). Microsoft customers are used to menus, choices and WYSIWYG (and
I'm too in the meantime). I've worked with IBMs DCF/GML for almost 10 years
being tired to stare at tagged plaintext to figure out, how it might look in
print.
I installed the DocBook 3.0 EDD(DTD) for FrameMaker and tested it. To be
frank, the content model (take Element Para for example) is overwhelming.
The naming conventions for elements are not consistent, so that related
elements are not near to each other in the (alphabetically sorted) valid
element list. The mixture of elements for articles, reference pages and
books in one content model makes the whole thing sort of clumsy and I guess,
hard to maintain too.
Looking forward to DocBook 5.0 (XML?), it may get worse, because XML doesn't
support SGMLs Include/Exclude.

My personel recommendation is:
split the DocBook-Standard into smaller one's with a common subset of
elements and attributes. Wrap similar elements (all list types) in higher
level structures (for example "Lists"), which can be unwrapped by XSLT, if
necessary.

What I will do instead?
I'm going to write a new, simplified and heavily reduced XML-DTD (hey, what
are nights and weekends for ;-) based on DocBook V4.1 and IBMIDDOC trying to
be as  DocBook conformant as possible.

Suggestions and comments are appreciated.



-----Original Message-----
From: docbook-tools-discuss-owner@sources.redhat.com
[ mailto:docbook-tools-discuss-owner@sources.redhat.com]On Behalf Of
Peter Toft
Sent: Monday, December 04, 2000 12:07 PM
To: docbook-tools-discuss@sourceware.cygnus.com
Subject: Where, what and how - The future of DocBook

RE: Where, what and how - The future of DocBook

[Pfaffner, Peter]

Hi all,
I'm new to this discussion list and not sure, if this is the right way to
reply to a topic (sorry if I'm wrong).

Peter Toft brought up an interesting Question:
>>>Many companies don't accept DocBook - why?
>>>Can't we do better???

I'm responsible for all kinds of technical standards for 12 months now. One
of them is documentation. Actually I decided to switch from MsWord ;-) to
FrameMaker+SGML for Windows and have to choose/create a company-DTD. To make
a long story short, I decided not to use DocBook as delivered.

Why?
Well, at first, our writers are not used to SGML/XML at all, or native SGML
authoring tools (thats the reason for an expensive WYSIWYG tool like
FM+SGML). And it is essential for a broad acceptance of the paradigm change
to make the switch as smooth as possible. Try to replace the good old
typewriter of your grandpa by a computer, and you know what I am talking
about :-). Microsoft customers are used to menus, choices and WYSIWYG (and
I'm too in the meantime). I've worked with IBMs DCF/GML for almost 10 years
being tired to stare at tagged plaintext to figure out, how it might look in
print.
I installed the DocBook 3.0 EDD(DTD) for FrameMaker and tested it. To be
frank, the content model (take Element Para for example) is overwhelming.
The naming conventions for elements are not consistent, so that related
elements are not near to each other in the (alphabetically sorted) valid
element list. The mixture of elements for articles, reference pages and
books in one content model makes the whole thing sort of clumsy and I guess,
hard to maintain too.
Looking forward to DocBook 5.0 (XML?), it may get worse, because XML doesn't
support SGMLs Include/Exclude.

My personel recommendation is:
split the DocBook-Standard into smaller one's with a common subset of
elements and attributes. Wrap similar elements (all list types) in higher
level structures (for example "Lists"), which can be unwrapped by XSLT, if
necessary.

What I will do instead?
I'm going to write a new, simplified and heavily reduced XML-DTD (hey, what
are nights and weekends for ;-) based on DocBook V4.1 and IBMIDDOC trying to
be as  DocBook conformant as possible.

Suggestions and comments are appreciated.



-----Original Message-----
From: docbook-tools-discuss-owner@sources.redhat.com
[ mailto:docbook-tools-discuss-owner@sources.redhat.com]On Behalf Of
Peter Toft
Sent: Monday, December 04, 2000 12:07 PM
To: docbook-tools-discuss@sourceware.cygnus.com
Subject: Where, what and how - The future of DocBook

Re: Where, what and how - The future of DocBook

[Norman Walsh]

| Fine - which tools are available for writing
| SGML/DocBook on Linux+xBSD or Windows?

The future is XML, not SGML.

| - Emacs and alike tools?

Naturally.

| - Any WYSIWYG editors?

That said, for Windows there are lots of XML editing tools coming
online. For production environments, I would recommend Arbortext's
Epic (disclaimer: I used to work for them). SoftQuad's XMetaL is less
expensive.

| - Any *fast* syntax verification system

James Clark's SP.

| - and what is being made in general

What is being made of what in general?

| Many companies don't accept DocBook - why?

Many companies do. Bug ones. With lots of documentation: Sun, HP,
Novell, etc. Who doesn't accept it (and why do you care that they
don't?)

| Can't we do better???

I'm sure we can.

| What is the future for SGML/DocBook versus XML/DocBook
| - again also regarding tools, the work efford going on
| at the moment etc.

XML is the future. But since XML is SGML, there's no loss here. You
can continue to use your favorite SGML tools. But I don't expect any
more SGML tools to be written. Ever.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com> | We dance around in a ring and suppose,
http://nwalsh.com/            | but the Secret sits in the middle and
                              | knows.--Robert Frost

Where, what and how - The future of DocBook

[Peter Toft]

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

Dudez - this is not to start a flamewar, so be positive
and think constructive now:

Many people agree that DocBook is the path to continue
along for Open Source program documentation and perhaps
also the system we should promote to use for document
handling in general.

Fine - which tools are available for writing
SGML/DocBook on Linux+xBSD or Windows?
- Emacs and alike tools?
- Any WYSIWYG editors?
- Any *fast* syntax verification system
- and what is being made in general

At the moment I write a lot in Emacs - but my mum would
not try that!!!

Many companies don't accept DocBook - why?
Can't we do better???

What is the future for SGML/DocBook versus XML/DocBook
- again also regarding tools, the work efford going on
at the moment etc.

Best regards

Peter/A DocBook user for several years now.

-- 
Peter Toft, Ph.D. [pto@sslug.dk] http://www.sslug.dk/~pto

"You don't win a battle by asking, `Will we win?'
You win it by doing your best to win" - Richard M Stallman

LinuxKonference i København: http://LinuxForum.dk/