[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: First pass for LDP-Author-Guide
> I'm not going to submit this to the LDP yet, since Jorge and I are
> working on some fine-tuning. However, I'd like the members to take
> a look at what we're working on and make suggestions before the first
Very nice update... some comments:
1. On your page about SGML conventions:
the link on the bottom to "conventions.sgml" is wrong. I got to
the file by removing the "/sgml/" that was in the link.
2. The images on:
did not appear on my system.
3. On the "Encoding Indexes" page at:
There is a typo in Example 5-3 caption - "attributte"
4. The "Book Example" on:
contained no information.
5. On the page about "DocBook Versions":
you indicate that all LDP headers should look like:
<!doctype article public "-//OASIS//DTD DocBook V3.1//EN">
So are we to assume from this that "<!doctype book public..." is
6. It would be nice to see the SGML source for thinks such as the
convention about command lines on:
7. The text about images on:
is now redundant with the text on:
8. I couldn't get the output HTML files to be named appropriately
when using openjade, but it did work with db2html. That should be
indicated somehow on:
unless I didn't do something right and it *will* work with openjade.
9. The images don't appear on my screen for:
10. On the page about CVS:
you might also want to add a pointer to:
The contents of that book that relate to CVS have been released
under the GPL and have been quite helpful to myself and others
trying to learn about CVS.
11. There is a page about *updating* CVS, but not about adding new
files to CVS. There should probably be some mention of this as
newbies to CVS may want to add new HOWTOs they write.
12. The numbering of sections seems to be inconsistent. Some of the
chapters of your original work seem to be be numbered okay, but
Jorge's sections don't seem to be numbered at all, and, as they
are in the middle of things, it seems somewhat strange.
13. As a potential new HOWTO author, it would be extremely helpful
if there was a "template" SGML document available that I could
download, open up, and start editing. It seems that most of
the HOWTOs have similar sections... like an "About this Guide",
Feedback, Copyrights and Trademarks, Acknowledgements and Thanks, etc.
There's also a basic way that it seems you want a section/chapter
to be created. The template could include the tags to start a
couple of sections.
If someone could create a shell of a HOWTO, with stuff like
"YOUR NAME HERE" or other obvious pointers of stuff to change,
then newbies to DocBook like me can download that, open it up,
make the appropriate changes, and start writing.
If such a template exists, I apologize but I don't know about it.
It would be very helpful if there was a link to such a template
14. Minor point... in step 5 under "Manual using jade/OpenJade" at:
shouldn't "-V nochunks" be tagged as <command> which would generate
a bold output? Currently it looks like <emphasis>
I guess that's all for now. *Many* thanks for writing this document
and your earlier document. They have been extremely helpful in helping
me get started using DocBook and I look forward to contributing more
to the LDP.
Dan York, Linuxcare, Inc.
1-603-264-0129 mobile, 603-268-0691 tel, 603-268-0103 fax
Linuxcare. Support for the revolution.
To UNSUBSCRIBE, email to email@example.com
with a subject of "unsubscribe". Trouble? Contact firstname.lastname@example.org