This is the mail archive of the 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]

Re: DocBook 4.0: ClassSynopsis

/ "Fred L. Drake, Jr." <> was heard to say:
| Norman Walsh writes:
|  > - The "verbish" names have been made "nounish". Exception has
|  >   been renamed ExceptionName, etc. Several of the elements will
|  >   also be made available inline.
|   But this is mixed.  I understand the desire to make the names
| similar to those of other, existing DocBook elements, but the lengthy
| names are one of the reasons I don't see that DocBook is a good match
| for my application (with lots of occaisional authors).

While I sympathize (even with Epic at my disposal, I do
occasionally edit DocBook documents "by hand" :-), DocBook has
always attempted to select clear, meaningful element names in
favor of short easy to type ones. (This is particularly
important in a DTD with fairly broad international use.) 

It is really, IMHO, a tools issue. But I do sympathize. Honest.

|  > - A ClassSynopsisInfo element was added
|   Perhaps this shows that I don't know enough about the existing
| DocBook, but ... what is the indended use?  Is this for a source-style 
| synopsis presentation as typically found in section 2 & 3 man pages?
| (I'm presuming this based on the content model and %linespecific.attrib;
| in the attribute list.)

No, it's for "stuff that doesn't fit in the model". For example,
in FuncSynopsis, it's how you can put a "#include" line in the
synopsis.  In ClassSynopsis, it's for other "verbatim" stuff
that doesn't have semantic markup. It's an escape hatch.
Consider the Perl case, which has "use" and "require" directives
that are somewhat analagous to the #include in a funcsynopsis, you
can use ClassSynopsisInfo for this:

<classsynopsis language="perl">

require 5.000;
use Carp;
use Symbol;

    <methodparam choice="opt"><parameter>$dirname</parameter></methodparam>

The fact that these elements end in "Info" is a bit unfortunate,
but if that warrants fixing, we can fix them both in, um, 6.0.

|   I'll try and take a look when I have a few minutes.  Hopefully this
| week.  -sigh-

Thanks. I expect we won't get a final 4.0 candidate until
mid-January, but the sooner we can get scrutiny on this
proposal, the better.


Norman Walsh <>      | A new scientific truth does not | triumph by convincing its
Member, DocBook Editorial Board    | opponents and making them see the
                                   | light, but rather because its
                                   | opponents eventually die, and a
                                   | new generation grows up that is
                                   | familiar with it (Planck 1949)

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