This is the mail archive of the docbook@lists.oasis-open.org mailing list for the DocBook project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: [docbook] First Attempt at Writing a Manual Not Going Well


On Thu, Apr 17, 2003 at 10:47:45AM -0700,
 Brian M. Sutin <sutin at ociw dot edu> wrote 
 a message of 99 lines which said:

>     When I actually try to sit down and write, I find myself
>     spending vastly more time paging throught the (relatively
>     incomprehensible) manual from O'Reilly that I do actually
>     entering information. 

Welcome to the club. Most DocBook users have had the same problems at
the beginning. Besides Norman Walsh, free software hero, it seems very
few (none?) people in the DocBook group care about usability.

>     DocBook appears to be something which grew, rather than
>     something which was designed. 

Right. It was designed by a commitee.

>     there could be a <who wrote this> wrapper which could be
>     included in sets, books, chapters, sectn, &c.  Instead,
>     there appears to be something slightly different for each.

A practical consequence: you should really use a syntactic editor (I
use Emacs/psgml) which tells you what can be entered or not at a given
point. That way, the editor has to know the DTD, not you.
          
<listitem><para>C-c C-t :
<command>sgml-list-valid-tags</command>
reminds you (or teaches you) the DTD. Very convenient when you start
playing with a monster like DocBook.</para> 
</listitem>

>     I would think that the importance of a piece of information
>     would be part of DTD, and not part of the style sheets.  Yet
>     the style sheets determine whether a particular bit of info
>     is printed or not.

It is the entire aim of a stylesheet. For instance, the <legalnotice>
may be important for the Legal Department but not for you and so you
do not display it when printing the drafts for a technical review. Or
the <footnote> can be suppressed when printing a summary (by
definition, a footnote is something that *can* be omitted).

>     (Not really DocBook)  Where can I learn about ENTITY?  Can I
>     use it as a sort of macro system for things I don't want to
>     type fifteen times?  

Yes. But it is not only to save typing (an editor could do it), it is
also to be consistent.

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
     "dtd/xml/4.1.2/docbookx.dtd"[
...
<!ENTITY lg "<foreignphrase>looking glass</foreignphrase>">
]>
<article lang="fr">
...
<para>Maintenant, comment savoir si nos routes à nous sont bien
      annoncées ? Le plus simple est d'utiliser un &lg;. </para>

> In summary, is there something I can go read that will educate me?
> DocBook for Dummies?  Idiots Guide to SGML?

I wrote one once but it is quite old and no longer maintained. I sent
it in private. 

My list of references (none fits your requirments):

http://www.tei-c.org/P4X/SG.html
http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/index.html
http://www.snee.com/bob/sgmlfree/





---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-unsubscribe at lists dot oasis-open dot org
For additional commands, e-mail: docbook-help at lists dot oasis-open dot org


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]