discuss: Thread: Docbook, Xml, Jade etc.

I've been working my way through the Author Guide and have become 
extremely frustrated.

Why do I need to install all of the various elements of this undocumented 
LDP cruft then learn how to use it in order to get a document published?

I've looked through the necessary packages, none of which 
contains _any_ documentation on install or usage. docbook-dssl handily 
mentions an install.html file but doesn't bother to provide it. Some of 
the packages uncompress into the current directory and try to overwrite 
files from other packages. Which versions should I use? This thing is an 
complete mess!

The Author guide is not much better; "you need this this and this" but not 
"this is how you install and configure the various pieces and start using 
them.."

Everyone reads HOWTO's in html anyway, why jump through all of the 
unnecessary hoops? Having to go through all of this rubbish to translate a 
perfectly good document from HTML into some unnecessary alternative format 
for the one in a billion people that doesn't have a browser is a complete 
waste of time.

-Simon.

Hello and welcome.

What linux distro are you using?

perhaps if you gave me your text, i could set up a bit
of it and it would get you on your way?

G




--- Simon Anderson ####@####.#### wrote:
> I've been working my way through the Author Guide
> and have become 
> extremely frustrated.
> 
> Why do I need to install all of the various elements
> of this undocumented 
> LDP cruft then learn how to use it in order to get a
> document published?
> 
> I've looked through the necessary packages, none of
> which 
> contains _any_ documentation on install or usage.
> docbook-dssl handily 
> mentions an install.html file but doesn't bother to
> provide it. Some of 
> the packages uncompress into the current directory
> and try to overwrite 
> files from other packages. Which versions should I
> use? This thing is an 
> complete mess!
> 
> The Author guide is not much better; "you need this
> this and this" but not 
> "this is how you install and configure the various
> pieces and start using 
> them.."
> 
> Everyone reads HOWTO's in html anyway, why jump
> through all of the 
> unnecessary hoops? Having to go through all of this
> rubbish to translate a 
> perfectly good document from HTML into some
> unnecessary alternative format 
> for the one in a billion people that doesn't have a
> browser is a complete 
> waste of time.
> 
> -Simon.
> 
> 
> ______________________
> http://lists.tldp.org/
> 


__________________________________
Do you Yahoo!?
Yahoo! SiteBuilder - Free, easy-to-use web site design software
http://sitebuilder.yahoo.com

[ Long reply.  Disclaimers below signature. ]

 : I've been working my way through the Author Guide and have become
 : extremely frustrated.

Yes, Simon, DocBook can be rather frustrating.  Indeed, terribly so
when you have to install all of the tools yourself.

 : Why do I need to install all of the various elements of this
 : undocumented LDP cruft then learn how to use it in order to get a
 : document published?

I see you have already had one offer for markup from a list member.
If you do have something you wish to write about, feel free to
ask--there are people on the list who will provide markup for you,
and also help you get your DocBook installation working.

Note, also, in my disclaimer below--you need not learn DocBook if
you do not wish to--you could use linuxdoc, an easier markup
language.  Others on this list do so, and are more familiar with
linuxdoc, so I'll continue in my determined effort as a proponent of
DocBook.

 : I've looked through the necessary packages, none of which
 : contains _any_ documentation on install or usage. docbook-dssl
 : handily mentions an install.html file but doesn't bother to
 : provide it. Some of the packages uncompress into the current
 : directory and try to overwrite files from other packages. Which
 : versions should I use? This thing is an complete mess!

Well....I'm not quite sure I'd agree with your assertion that there
is no documentation on installation or usage....BUT, the easily
available existing documentation is sometimes at cross purposes due
to the myriad ways in which DocBook can be used.

One beautiful thing about DocBook...it's just a bunch of files.  (Of
course, I suppose you could almost say the same about Unix.)

 : The Author guide is not much better; "you need this this and
 : this" but not "this is how you install and configure the various
 : pieces and start using them.."
 :
 : Everyone reads HOWTO's in html anyway, why jump through all of
 : the unnecessary hoops?

Although it's true that *many* people read HOWTOs in HTML, I have
found that the most common download of my own documentation is the
PDF (which is generated from the same source DocBook files).

So, there are people who use other output formats, although I would
agree with the sentiment of your frustration--people probably read
(or refer) to the HTML documentation, not the PS or PDF output.

 : Having to go through all of this rubbish to translate a perfectly
 : good document from HTML into some unnecessary alternative format
 : for the one in a billion people that doesn't have a browser is a
 : complete waste of time.

The primary reason you might choose to write DocBook is to separate
the presentation (which will be primarily HTML) from the content and
organization, which is the DocBook SGML/XML format.

[ /me omits section on DocBook SGML, since I don't know it very
  well, but it's like any other markup language you might already
  have experience with. ]

So DocBook XML is an XML dialect which represents an entire book or
document in a structured manner, without hinting at the
presentation.



   ** High-level overview **

DocBook XML can be a bit confusing at first, so let's identify the
different files you need in order to process DocBook files.


  Files in use in any DocBook processing installation

           DocBook XML (processed with jade)
           ------------------------------------------
             DTD files (you probably want 4.1.2)
             DSSSL files (1.78 is current)


           DocBook XML (processed with xsltproc*)
           ------------------------------------------
             DTD files (you probably want 4.1.2)
             XSLT files (1.61.3 is current)


  Brief description of the purpose of these files

     - DTD files define the acceptable structure and tags of any
       DocBook file.  The processor (jade or xsltproc) consults
       the DTD files to validate any DocBook source file.

     - DSSSL files are used by jade to map DocBook documents into
       HTML output.  If you intend to use jade, you must have the
       DSSSL files in order to generate output.

     - XSLT files are used by xsltproc to map DocBook XML documents
       into HTML output.  If you intend to use xsltproc, you must
       have the XSLT files.


So, you can think of the DTD as a blueprint against which a document
is checked for validity, and you can think of the DSSSL and XSLT
files as translators or interpreters.  A processor needs to compare
an input document with a validity structure and uses DSSSL/XSLT to
transform the input document into a desired output format.

That's just a touch of background.



   ** Preparing the support files **

Because I know I'm the only user on my workstation, I do roughly the
following (use a mirror near you):

Getting the files in one place:

$ cd $HOME
$ mkdir docbook
$ cd docbook
$ wget http://umn.dl.sourceforge.net/sourceforge/docbook/docbook-dsssl-1.78.tar.gz
$ tar xvzf docbook-dsssl-1.78.tar.gz
$ ln -s docbook-dsssl-1.78 dsssl
$ wget http://umn.dl.sourceforge.net/sourceforge/docbook/docbook-xsl-1.61.3.tar.gz
$ tar xvzf docbook-xsl-1.61.3.tar.gz
$ ln -s docbook-xsl-1.61.3 xsl
$ wget http://www.tldp.org/authors/tools/docbkx412.zip
$ mkdir -p dtds/4.1.2
$ cd dtds/4.1.2
$ unzip ../../docbkx412.zip

Now, this should give you all of the XSLT, DSSSL, and DTD files in
one centrally accessible location for your UID.



   ** The catalog file **

Now, there is exactly and only one tricky step left.  That is the
use of a catalog file to tell your processor where to find the
required files.

Problem:

    The DocBook DTDs are known by public identifiers (you have seen
    these at the top of files:

      -//OASIS//DTD DocBook V4.1.2//EN
      -//OASIS//DTD DocBook V4.1//EN

    The DocBook XSL stylesheets are known by an absolute URL.

Solution:

    Make the processor capable of referring to a local file instead of
    an HTTP resource or an abstract concept (a public identifier).

This is a catalog file.  (Frequently called catalog.xml.)

[ Sorry for the long lines, list readers. And yes, my "nextCatalog" tag
  is broken ]

  <?xml version="1.0"?>
  <!DOCTYPE catalog PUBLIC "-//OASIS/DTD Entity Resolution XML Catalog V1.0//EN"
          "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">

  <catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
          <nextCatalog catalog="@XML_CATALOG@" />
    <public
       publicId="-//OASIS//DTD DocBook XML V4.1.2//EN"
       uri="/home/mabrown/docbook/dtds/4.1.2/docbookx.dtd"/>
    <uri name="http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
       uri="/home/mabrown/docbook/dtds/4.1.2/docbookx.dtd"/>
    <uri name="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"
       uri="/home/mabrown/docbook/xsl/xhtml/docbook.xsl"/>
    <uri name="http://docbook.sourceforge.net/release/xsl/current/xhtml/chunk.xsl"
       uri="/home/mabrown/docbook/xsl/xhtml/chunk.xsl"/>
    <uri name="http://docbook.sourceforge.net/release/xsl/current/xhtml/profile-chunk.xsl"
       uri="/home/mabrown/docbook/xsl/xhtml/profile-chunk.xsl"/>

  </catalog>


Convention may differ, but I keep the catalog file with the
documentation itself, not with the DocBook XSL, DSSL and DTD files.
So, in every project I make, I have a catalog.xml.



   ** Creating an ouput document (chunked HTML) **

And finally, a very simple example of using xsltproc to generate
HTML output from a DocBook XML source file.  I will give you an
example of an XML catalog file I use for one of my pieces of
documentation.  If you'd like to try, yourself, just grab a DocBook
XML file from the
http://cvsview.tldp.org/index.cgi/LDP/howto/docbook/ repository.
Make sure it is a DocBook XML file, this should be clear in the
header.

$ cd $DOC_SRC_DIR
$ mkdir output
$ export XML_CATALOG_FILES=catalog.xml
$ xsltproc --nonet -stringparam base.dir output \
> ~/docbook/xsl/xhtml/chunk.xsl $DOCBOOK_DOCUMENT

Now, you should have some HTML files in the directory output.  And,
by the way, I'd recommend the newest version of xsltproc that you
can get your hands on.  There was/is a very old version floating
around on RedHat boxen (libxslt-1.0.18, I think) which doesn't like
DocBook XSLT very much.


   ** Conclusion **

So, Simon--YES--DocBook is difficult and frustrating, but you will
be able to rid yourself of the drudgery of maintaining HTML files
by conquering DocBook.  If you have one or two short HTML files,
DocBook is probably overkill, but for TLDP, it meets a need.  Small
and simple documents like my Traffic Control with tcng and HTB can
be written in DocBook, and large and complex book-length documents
like the Advanced Bash Scripting Guide can also be written in
DocBook.

And if you have just a short item to write--feel free to write it in
text, and ask somebody on the list to tag it for you.

Good luck, and let us know how it goes,

-Martin

  * There are other XSLT processors (saxon, xalan, et.al.), which
    can also produce output from DocBook XML source.  These XSLT
    processors also need to read the XSLT and DTD files.


disclaimers:

  It is not required to use DocBook.  TLDP will accept submissions
  in linuxdoc format, which is a much simpler markup language, and
  one preferred by several regular contributors.

  The above method of setting up a user for DocBook processing is
  quick n' dirty, and is not suitable for a system which will
  routinely be used by many to build documentation.

  I did not include any examples on how to create HTML output from
  and/or with jade, because this was just a crash course.

Dear Simon,

> I've been working my way through the Author Guide and have become
> extremely frustrated.

Very similar to my experience.

> Everyone reads HOWTO's in html anyway, why jump through all of the
> unnecessary hoops? Having to go through all of this rubbish to translate a
> perfectly good document from HTML into some unnecessary alternative format
> for the one in a billion people that doesn't have a browser is a complete
> waste of time.

This paragraph is the only one I don't agree with.

As for the rest of your experience, I had a very similar experience.
Luckily, I had a colleague who I could ask to work on this setup task
full-time, and he set things up for me. (The HOWTO that I maintain is a
company-mandated task. Lucky for me.)

My attitude to all these problems has been slightly different. I've
looked at whatever I've got from TLDP by way of assistance as
"volunteer work." Everyone here does the best he can. So instead of
getting upset at the problems, I saw them as opportunities to improve
things. Once I get the time to write a better Author's Guide, I'll do
it. Till then, I think I should just work around the limitations. No
point getting upset about the work done by some bloody sincere and
helpful people; let's help them if we can.

Shuvam

On Mon, 28 Jul 2003, Shuvam Misra wrote:
> My attitude to all these problems has been slightly different. I've
> looked at whatever I've got from TLDP by way of assistance as
> "volunteer work." Everyone here does the best he can. So instead of
> getting upset at the problems, I saw them as opportunities to improve
> things. Once I get the time to write a better Author's Guide, I'll do
> it. Till then, I think I should just work around the limitations. No
> point getting upset about the work done by some bloody sincere and
> helpful people; let's help them if we can.

Not good enough.

My motivation as an author is to provide worthwhile content to as many 
people as possible that may find it useful. 

I look to the LDP to facilitate my work getting used by it's intended 
audience. 

Instead, I find the LDP creating obstructions to this process rather than 
facilitating it, by requiring me to jump through a series of poorly 
documented hoops in order to meet some arbitrary (and ultimately 
pointless) criteria.

Instead of improving my content, I am wasting countless hours working 
step by step through the Author Guide, only to get output like the 
following. This is not worthwhile use of any author's time.

I ask you to consider what Stephen King needs to know about printing 
presses and type setting. Further, I ask that you consider how many 
authors like me decide that the LDP just isn't worth the effort.

-Simon.

[root@dalton sgml]# jade -t sgml -i html -d dssl/ldp.dsl 
/usr/share/sgml/xml.dcl test.xml
jade:/usr/local/sgml/dssl/catalog:28:0:W: DTDDECL catalog entries are not 
supported
jade:/usr/local/sgml/dtd/docbook.cat:22:0:W: DTDDECL catalog entries are 
not supported
jade:test.xml:1:0:E: end of document in prolog
jade:/usr/local/sgml/dssl/catalog:28:0:W: DTDDECL catalog entries are not 
supported
jade:/usr/local/sgml/dtd/docbook.cat:22:0:W: DTDDECL catalog entries are 
not supported
jade:dssl/catalog:28:0:W: DTDDECL catalog entries are not supported
jade:/usr/local/sgml/dssl/catalog:28:0:W: DTDDECL catalog entries are not 
supported
jade:/usr/local/sgml/dtd/docbook.cat:22:0:W: DTDDECL catalog entries are 
not supported
jade:dssl/ldp.dsl:2:54:W: cannot generate system identifier for public 
text "-//James Clark//DTD DSSSL Style Sheet//EN"
jade:dssl/ldp.dsl:16:0:E: reference to entity "STYLE-SHEET" for which no 
system identifier could be generated
jade:dssl/ldp.dsl:1:0: entity was defined here
jade:dssl/ldp.dsl:16:0:E: DTD did not contain element declaration for 
document type name
jade:dssl/ldp.dsl:6:0:E: notation "DSSSL" for entity "docbook.dsl" 
undefined
jade:dssl/ldp.dsl:18:12:E: element "STYLE-SHEET" undefined
jade:dssl/ldp.dsl:40:24:E: there is no attribute "ID"
jade:dssl/ldp.dsl:40:36:E: there is no attribute "USE"
jade:dssl/ldp.dsl:40:45:E: element "STYLE-SPECIFICATION" undefined
jade:dssl/ldp.dsl:41:25:E: element "STYLE-SPECIFICATION-BODY" undefined
jade:dssl/ldp.dsl:132:44:E: element "STYLE-SPECIFICATION" undefined
jade:dssl/ldp.dsl:133:25:E: element "STYLE-SPECIFICATION-BODY" undefined
jade:dssl/ldp.dsl:362:27:E: there is no attribute "ID"
jade:dssl/ldp.dsl:362:46:E: there is no attribute "DOCUMENT"
jade:dssl/ldp.dsl:362:59:E: element "EXTERNAL-SPECIFICATION" undefined
jade:dssl/ldp.dsl:364:13:E: end tag for "EXTERNAL-SPECIFICATION" omitted, 
but its declaration does not permit this
jade:dssl/ldp.dsl:362:0: start tag was here
jade:E: specification document does not have the DSSSL architecture as a 
base architecture

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

On Sun, 27 Jul 2003, Simon Anderson wrote:

> I've been working my way through the Author Guide and have become 
> extremely frustrated.
> 
> Why do I need to install all of the various elements of this undocumented 
> LDP cruft then learn how to use it in order to get a document published?

Patience, please.  Note that Emma Jane Hogbin is reviewing this Guide for 
making it less scary.

Tille.

- -- 

My Penguin, my freedom.		http://tille.soti.org

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.7 (GNU/Linux)

iD8DBQE/JLHCsIIUbMXbBA8RAkVgAKCwF4KIp31RUudowqrLTmUThudMvgCfYqdY
Pyu2FbyEOASpL7i/Flyqocc=
=fbjO
-----END PGP SIGNATURE-----

This one time, at band camp, Simon Anderson ####@####.#### wrote:
> Instead of improving my content, I am wasting countless hours working 
> step by step through the Author Guide, only to get output like the 
> following. This is not worthwhile use of any author's time.

http://www.lodestar2.com/people/dyork/talks/2002/ols/docbook-tutorial/frames/frames.html
Takes about 5 minutes to learn docbook xml by reading that.

> I ask you to consider what Stephen King needs to know about printing 
> presses and type setting.

Nothing, which is precisely why DocBook is being used, rather than 
presentation-level html where you'd have to worry about something like 
that.

Morgon
-- 
"Man is the only creature capable of hating itself" -- Governor of Japan 
in The End of Evangelion

> Instead of improving my content, I am wasting countless hours working
> step by step through the Author Guide, only to get output like the
> following. This is not worthwhile use of any author's time.
>
> I ask you to consider what Stephen King needs to know about printing
> presses and type setting. Further, I ask that you consider how many
> authors like me decide that the LDP just isn't worth the effort.

I agree. I agree. And I believe most people in the LDP too will agree
with you that any difficulties faced in infrastructure setup will put
off valuable potential authors. So, yes, the assistance you get from the
Author's Guide or other online help is not "good enough."

All I'm saying is that I treat this as "volunteer work", therefore I
prefer to figure out a workaround, or figure out a way to contribute to
improving it. No point wasting my energy getting upset over the parts
which are not good enough; let's just improve things. It's a long and
very hard upward trudge, and all LDP veterans will probably agree on
this.

Shuvam

Simon Anderson wrote:

> Not good enough.
> 
> My motivation as an author is to provide worthwhile content to as many 
> people as possible that may find it useful. 
> 
> I look to the LDP to facilitate my work getting used by it's intended 
> audience. 

I didn't look at the author guide for a long time now, but I think it 
should begin by this (or similar) words:

"Future LDP author, don't bother about the format you write your text, 
but focuse on the content. What ever should the format be, there will be 
some LDP voluteer to help give it the necessary formatting.

go ahead on this guide if you intend to become a regular LDP author and 
want so to learn the necessary Docbook elements, but don't let this mess 
you out of business..."

I know I personnaly _don't_ like to see anybody touch my text :-(, but 
nobody is obliged to be like me :-)

jdd

-- 
<http://www.dodin.net>
Formation Linux débutants open

hi

true. you got the right to complain but instead of
ranting be critical with ideas to improve and take up
some of the work. this would encourage others to
participate

example:

these are thelist of bad things

a 
b
c

i am working on a. can somebody take care of b and c
would yeild better results. considering its a
volunteer effort i appreciate everything being done
here.

regards
rahul sundaram
 --- Shuvam Misra ####@####.#### wrote:
> > Instead of improving my content, I am wasting
> countless hours working
> > step by step through the Author Guide, only to get
> output like the
> > following. This is not worthwhile use of any
> author's time.
> >
> > I ask you to consider what Stephen King needs to
> know about printing
> > presses and type setting. Further, I ask that you
> consider how many
> > authors like me decide that the LDP just isn't
> worth the effort.
> 
> I agree. I agree. And I believe most people in the
> LDP too will agree
> with you that any difficulties faced in
> infrastructure setup will put
> off valuable potential authors. So, yes, the
> assistance you get from the
> Author's Guide or other online help is not "good
> enough."
> 
> All I'm saying is that I treat this as "volunteer
> work", therefore I
> prefer to figure out a workaround, or figure out a
> way to contribute to
> improving it. No point wasting my energy getting
> upset over the parts
> which are not good enough; let's just improve
> things. It's a long and
> very hard upward trudge, and all LDP veterans will
> probably agree on
> this.
> 
> Shuvam
> 
> 
> ______________________
> http://lists.tldp.org/
>  

________________________________________________________________________
Send free SMS using the Yahoo! Messenger. Go to http://in.mobile.yahoo.com/new/pc/