Re: First pass for LDP-Author-Guide

[Dan York <dyork@linuxcare.com>]

Mark,

> 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
> release.

Very nice update... some comments:

1. On your page about SGML conventions:

    http://www.cgipc.com/~markk/LDP-Author-Guide/conventions.html

   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:

    http://www.cgipc.com/~markk/LDP-Author-Guide/making-catalogues.html

   did not appear on my system.

3. On the "Encoding Indexes" page at:

    http://www.cgipc.com/~markk/LDP-Author-Guide/encoding-index.html
  
   There is a typo in Example 5-3 caption - "attributte"

4. The "Book Example" on:

    http://www.cgipc.com/~markk/LDP-Author-Guide/examples-documents.html

   contained no information.

5. On the page about "DocBook Versions":
    
    http://www.cgipc.com/~markk/LDP-Author-Guide/x1971.html

   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
   not acceptable?  

6. It would be nice to see the SGML source for thinks such as the
   convention about command lines on:

     http://www.cgipc.com/~markk/LDP-Author-Guide/x1986.html

7. The text about images on:

     http://www.cgipc.com/~markk/LDP-Author-Guide/tips.html

   is now redundant with the text on:

     http://www.cgipc.com/~markk/LDP-Author-Guide/inserting-pictures.html

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:

     http://www.cgipc.com/~markk/LDP-Author-Guide/x2030.html

   unless I didn't do something right and it *will* work with openjade.

9. The images don't appear on my screen for:

     http://www.cgipc.com/~markk/LDP-Author-Guide/x2042.html

10. On the page about CVS:

      http://www.cgipc.com/~markk/LDP-Author-Guide/cvs.html

    you might also want to add a pointer to:

      http://cvsbook.red-bean.com/

    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
    here.

14. Minor point... in step 5 under "Manual using jade/OpenJade" at:

      http://www.cgipc.com/~markk/LDP-Author-Guide/getstarted.html#AEN332

    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.

Regards,
Dan
--
Dan York,  Linuxcare, Inc.
dyork@linuxcare.com    http://www.linuxcare.com/
1-603-264-0129 mobile, 603-268-0691 tel, 603-268-0103 fax
Linuxcare.  Support for the revolution.


--  
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org