OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]


Subject: Re: DOCBOOK: DocBook 4.0: ClassSynopsis


/ "Fred L. Drake, Jr." <fdrake@acm.org> 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">
  <classname>DirHandle</classname>

  <classsynopsisinfo>
require 5.000;
use Carp;
use Symbol;
</classsynopsisinfo>

  <constructorsynopsis>
    <methodname>new</methodname>
    <methodparam choice="opt"><parameter>$dirname</parameter></methodparam>
  </constructorsynopsis>
...
</classsynopsis>

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.

                                        Cheers,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | A new scientific truth does not
http://www.oasis-open.org/docbook/ | 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)



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]


Powered by eList eXpress LLC