RE: DocBook function synopsis

["Frank A. Christoph" <christo@xxxxxxxxxxxxxxxxxx>]

>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 "
  Class   CDATA #IMPLIED
  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
code...

;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 ")
             (empty-sosofo))
           (process-children)
           (if (string=? (attribute-string (normalize "const") funcdef)
                         (normalize "const"))
             (literal " const")
             (empty-sosofo))
           (if (string=? dispatch-val (normalize "pure"))
             (literal " = 0")
             (empty-sosofo))
           (literal ";"))
     (if (equal? %funcsynopsis-style% 'kr)
       (with-mode kr-funcsynopsis-mode
                  (process-node-list paramdefs))
       (empty-sosofo)))))

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

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

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

With these changes, you can format things like

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

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.

--FC



 DSSSList info and archive:  http://www.mulberrytech.com/dsssl/dssslist