Re: defxx regression in docbook output cvs texinfo

[Per Bothner]

On 07/22/2012 01:14 AM, Patrice Dumas wrote:
> On Sat, Jul 21, 2012 at 10:25:00AM -0700, Per Bothner wrote:
> > I agree.  Updated patch attached.
>
> Thanks, applied!
>
> As a side note, I'd like to replace some @def* with specialized docbook
> synopsis.  I see 2 possibilities:
>
> 1) Use *synopsis for specialized @def*:
>
> funcsynopsis for @defun and @deftypefun, fielsdsynopsis for @defivar and
> @deftypeivar, classsynopsis for @defmethod and @deftypemethod.

The devil in in the details.

"Unlike cmdsynopsis and funcsynopsis which have a complex interior 
structure,
synopsis is simply a verbatim environment."

and

"Using funcsynopsis for languages that are unrelated to C may prove 
difficult."

One reason is:

"For the most part, the processing application is expected to generate 
all of the parentheses, semicolons, commas, and so on required in the 
rendered synopsis. The exception to this rule is that the spacing and 
other punctuation inside a parameter that is a pointer to a function 
must be provided in the source markup."

I.e. the processing application (e,g, the xslt stylesheets) need to
know the syntax of the described language - which is impractical.

> For those there wouldn't be the phrase you added.
>
> 2) use *synopsisinfo for the category
>
> In that case <*synopsis> would be used for most of the @def* the category
> would be put in <*synopsisinfo>.  Like:
>
> defop:
> <classsynopsis><classsynopsisinfo>category</classsynopsisinfo><ooclass><classname>class<><><methodsynopsis><methodname><replaceable><></methodname><methodparam><parameter>...<><><>
>
> Thus the <phrase> would be left only for the @def* that have no
> corresponding synopsis, like @defopt.

This seems moot unless you can solve tehe problems of (1).

> does one of those possibility looks good?

DocBook is supposed to be extensible, and we can certainly extend DocBook.
But I think that's we'd be talking about.  And that requires updates
stylesheets.

Without looking too deeply into the issues, my feeling is we should avoid
going this way, at least for now.  Maybe for texinfo 6.0 ...
--
        --Per Bothner
address@hidden   http://per.bothner.com/