Subject:
Re: DocBook-OpenJade-SGML-XML-HOWTO :: review
From:
####@####.####
Date:
9 Aug 2002 02:22:30 -0000
Message-Id: <OF5C7CA6FC.4C0688D8-ON88256C10.000CE9A4@notes.seagate.com>
Hi Loyd,
Thanks for the corrections and revisions. I will be making these revision
over the weekend.
I still have to work on a example for XML. :)
Thanks
Saqib Ali
"Lloyd D
Budd" To: ####@####.####
<ldp@foolswis cc: "ldp" ####@####.####
dom.org> Subject: DocBook-OpenJade-SGML-XML-HOWTO :: review
No Phone Info
Available
08/07/2002
07:57 PM
Hello saqib,
Another excellent HOW-TO! As is my nature, my review is pedantic...ignore
what you will,
as there is are no significant issues, except possibly not including an XML
example. You are legally required to have to have an example if you want
XML in the title ;-)
NOTE: excuse any apparent ignorance, as in this initial pass, I did not
execute any of the commands. I am on Windows, using MS Outlook Express
(w/o
spell check). Please forgive any Evil (TM)...I am travelling on business
and have yet to find time to configure this laptop: setup 'mutt' on MSWin;
or better yet backup data, and get Linux installed.
> SGML/XML) documents to HTML, RTF, and PDF.
On 1st use, define the acronyms.
> DocBook is document type definition (DTD). DocBook is a commonly
> used DTD for writing technical documents. A DTD defines the syntax
> of a document - essentially it is a 'rule book' that describes the sets
of
> tags and attributes that will be used to describe specific kinds of
content.
> So DocBook is a "Rule Book" that is used for writing documents. Every
> TAG that is used in writing the document, must be defined verfy
specifically
> and formally in the DTD.
Although technically correct, your very logical explaination is overly
verbose.
I would suggest:
DocBook is a document type definition (DTD). A DTD defines the syntax
of a document. DocBook describes the types of structure and formats to use
in technical documents. It is commonly used because of its simplicity and
completeness.
ASIDE: "defined verfy specifically" has a typo.
> 1.3. What is DSSSL?
>
> A Document Style Semantics and Specification Language (DSSSL) defines
> how to convert an SGML document into a human-readable format.
This is the first time that you have mentioned SGML outside of the Intro.
You should also describe it.
> LDP DSL
1st use, define these acronyms.
> All of these packages are free and are available for download on the net.
Very minor. All of these packages are free and available for download on
the net.
> The only tool that you is compiled is OpenJade.
typo, but it is also mentioned on the next page. I would suggest dropping
the whole statement:
> The only tool that you is compiled is OpenJade. The rest of the tools
have
to be
> extracted and placed in the right directories.
as it is completely described on the next page.
> gzip or gunzip - available from http://www.gnu.org
You use gzip throughout, so should be:
gzip - available from http://www.gnu.org
> 2.1. Pre-requirements
>
> Create a directory /tmp/downloads. We will use this directory to
> store the downloaded source code.
This does not fit well here, considering what is ahead. It would be great
to put in 3.2. (In 3.1 step 1, you show creating another dir, you may
consider adding '-p' to both, for ensurance)
> Please download the whole zip archive.
Looking @ http://www.tldp.org/authors/index.html#resources , what whole zip
archive, you are referring to, is not clear. Is it the same thing as the
following. Then why the redundancy?
> 2.4. ISO Entities
> The Linux Documentation Project has packaged all the Entities into one
big
> tar file and placed it at
http://www.tldp.org/authors/index.html#resources
> for the convenience of the users. Thanks to TLDP for this.
What does ISO Entities refer to? It would be good to define, and to
document
the file name as 'entities.tar.gz' It is "big" an approximation of size
would be benefitial.
> Thanks to TLDP for this.
This is the 2nd time u use TLDP. But you still have not defined it to be
The Linux Documentation Project.
> 2.7. HTMLDOC
This was not identified as a needed aspect in
> 1.4. What do we need?
given this, 2.7 seems out of place:
> HTMLDOC can be used for converting the HTML to PDF.
> If you would like to produce PDF documents, please download
> HTMLDOC from http://www.easysw.com/htmldoc/software.php
also only later in 3.6 do you describe this as optional.
> 3.3
I am not in the know, but I am not a big fan of not putting DocBook or
(docbknn) in the path name. Potentially, other 'dbtools' (ick name as db
generally refers to database) -> programs could have dtds
> 3.3
you refer to DocBook SGML v3.1 , DocBook SGML v4.1 , DocBook SGML v4.1.2 ,
but back in 2.3 you refer to DocBook SGML v4.1, DocBook SGML v3.1, and
DocBook XML v4.1.2 . How did XML become SGML or vice versa? ;-)
> 3.5. Installing LDP DSL
> Finally we install the ldp.dsl.
very minor, should probably be "Finally we install the ldd dsl.
> # cp ldp.dsl
> /usr/local/dbtools/docbook-dsssl/print/ldp.dsl
Why new line? Step 3 is one character shorter and does not wrap. Is it my
browser? (too lazy to look @ html source, but imagine that it is <code>)
> 3. 5
Step 3, typo: ">Copy"
> 4.4. HTML to PDF
This is dependant on an optional section, so this section should also be
optional.
> 4
None of your examples show a conversion involving XML!
> 5. Further Information
There is great irony when you only reference TLDP as a related Mailing List
resource, considering your previous references in the HOW-TO! :-D
Cheers,
Lloyd D Budd
