RE: DocBook function synopsis

Subject: RE: DocBook function synopsis
From: "Frank A. Christoph" <christo@xxxxxxxxxxxxxxxxxx>
Date: Thu, 9 Jul 1998 12:42:13 +0900
>The answer
>is probably that there _is_ no good way to do it in a
>FuncSynopsis at this time.  the FuncSynopsis content model was
>designed to handle C functions, not C++ functions.
>| just wanted to ask the same question one more time, and then I'll shut up
>| and just modify the DTD myself.
>I haven't had time to think about what I think the answer should
>be, but if/when you modify the DTD, please share your
>modifications.  Updating FuncSynopsis to handle a broader range
>of programming languages seems like a good idea.

I wasn't planning on making any major changes, just enough that I can handle
pure and const member functions.  Anyway, here is a first shot, sufficient
for my purposes. (This is the result of about 15 minutes work, so if someone
has any better ideas, or if it turns out that I'm "violating the spirit of
Docbook" in some way, I'll be happy to entertain other ideas.)

I added three attributes to FuncDef in the declaration subset, "Class" which
indicates what class the function is a member of (I'm not using it, but it
seems potentially useful); "Dispatch" which would be "pure" for pure virtual
functions, "virtual" for regular dynamically dispatched functions, and
"static" for statically dispatched functions; and finally "Const" which is
"const" for functions that don't modify the state, or "mutable" for those
that do.

<!-- customizations -->
<!ENTITY % local.funcdef.attrib "
  Dispatch (pure|virtual|static) static
  Const   (const|mutable) mutable" >

And here is the modified formatting code.  These are based on the
definitions in docbook/print/dbsynop.dsl; I haven't looked at the HTML

;changes to support C++ member functions and Docbook customizations
(element funcprototype
  (let* ((paramdefs (select-elements (children (current-node))
         (normalize "paramdef")))
        (funcdef (node-list-first (children (current-node))))
        (dispatch-val (attribute-string (normalize "dispatch") funcdef)))
    (make sequence
     (make paragraph
           font-family-name: %mono-font-family%
           (if (or (string=? dispatch-val (normalize "virtual"))
                   (string=? dispatch-val (normalize "pure")))
             (literal "virtual ")
           (if (string=? (attribute-string (normalize "const") funcdef)
                         (normalize "const"))
             (literal " const")
           (if (string=? dispatch-val (normalize "pure"))
             (literal " = 0")
           (literal ";"))
     (if (equal? %funcsynopsis-style% 'kr)
       (with-mode kr-funcsynopsis-mode
                  (process-node-list paramdefs))

(element void
  (if (equal? %funcsynopsis-style% 'ansi)
      (literal "(void)")
      (literal "()")))

(element varargs (literal "(...)"))

(element paramdef
  (let ((param (select-elements (children (current-node)) (normalize
    (make sequence
      (if (equal? (child-number (current-node)) 1)
   (literal "(")
      (if (equal? %funcsynopsis-style% 'ansi)
   (process-node-list param))
      (if (equal? (gi (ifollow (current-node))) (normalize "paramdef"))
   (literal ", ")
   (literal ")")))))

With these changes, you can format things like

<funcdef pure const>int <function/foo/</funcdef>
<paramdef/Bar */

to look like

virtual int foo(Bar *) const = 0;

Note: I don't think formatting for K&R is correctly preserved by these
changes, although a slight change looks like it would be sufficient.

Comments/improvements welcome.


 DSSSList info and archive:

Current Thread
  • DocBook function synopsis
    • Frank A. Christoph - from mail1.ability.netby (8.8.5/8.6.12) with ESMTP id WAA18410Sun, 5 Jul 1998 22:55:30 -0400 (EDT)
      • <Possible follow-ups>
      • Frank A. Christoph - from mail1.ability.netby (8.8.5/8.6.12) with ESMTP id XAA29146Tue, 7 Jul 1998 23:13:17 -0400 (EDT)
        • Norman Walsh - from mail1.ability.netby (8.8.5/8.6.12) with ESMTP id IAA12156Wed, 8 Jul 1998 08:15:53 -0400 (EDT)
      • Frank A. Christoph - from mail1.ability.netby (8.8.5/8.6.12) with ESMTP id XAA11708Wed, 8 Jul 1998 23:33:04 -0400 (EDT) <=
        • Lionel Mallet - from mail1.ability.netby (8.8.5/8.6.12) with ESMTP id DAA16760Thu, 9 Jul 1998 03:02:38 -0400 (EDT)
        • Mitch C. Amiano - from mail1.ability.netby (8.8.5/8.6.12) with ESMTP id RAA02041Thu, 9 Jul 1998 17:03:33 -0400 (EDT)
      • Frank A. Christoph - from mail1.ability.netby (8.8.5/8.6.12) with ESMTP id DAA20422Thu, 9 Jul 1998 03:45:12 -0400 (EDT)
      • Frank A. Christoph - from mail1.ability.netby (8.8.5/8.6.12) with ESMTP id WAA27256Thu, 9 Jul 1998 22:45:28 -0400 (EDT)