Stefan Seefeld | 27 Apr 2012 17:28

Fine-grained markup in stylised function name

Hello,

I'm trying to transcribe an C API specification into DocBook 5. The API
specification describes a class of functions like "create_f",
"create_d", "create_i", using a typographical convention that uses
specially marked-up characters within a function name that act as
placeholders. Thus, instead of having to explicitly list all the
variant, a single name is used representing all of them.

I would like to map this to DocBook, but have quite some difficulties.
There doesn't appear to be any DB element that is suitable to mark up
characters in a name, without severely restricting where such names may
appear. (Specifically, in my case these names need to appear in <title>,
<functionname>, et al.

For an example of the desired output, please see
http://www.vsipl.org/VSIPL1p3.pdf, notably the chapter "Summary of VSIPL
Types".)

Any suggestion how to approach this ? Or do I need to extend the DB
grammar (and stylesheets) to get what I need ?
I fully appreciate that the desire to explicitly style words or even
characters is contrary to the DB philosophy of separating content from
style. However, arguably in this case the styling is the content, i.e.
is part of the semantics that need to be expressed. Thus I would very
much prefer to find a solution within the DB grammar, if at all possible.

Suggestions ?

Thanks,
(Continue reading)

rob.cavicchio | 27 Apr 2012 17:35

RE: Fine-grained markup in stylised function name

Stefan Seefeld [mailto:stefan <at> seefeld.name] wrote:

> I'm trying to transcribe an C API specification into DocBook 5. The API
> specification describes a class of functions like "create_f",
> "create_d", "create_i", using a typographical convention that uses
> specially marked-up characters within a function name that act as
> placeholders. Thus, instead of having to explicitly list all the
> variant, a single name is used representing all of them.
> 
> I would like to map this to DocBook, but have quite some difficulties.
> There doesn't appear to be any DB element that is suitable to mark up
> characters in a name, without severely restricting where such names may
> appear. (Specifically, in my case these names need to appear in
> <title>,
> <functionname>, et al.

Unless I'm misunderstanding, this is the purpose of the <replaceable> element.

*************************
Rob Cavicchio
rob.cavicchio <at> emc.com

Principal Technical Writer & Information Architect
Information Intelligence Group
EMC Corporation

The opinions expressed here are my personal opinions. Content published here is not read or approved in
advance by EMC and does not necessarily reflect the views and opinions of EMC.
Stefan Seefeld | 27 Apr 2012 17:50

Re: RE: Fine-grained markup in stylised function name

On 04/27/2012 11:35 AM, rob.cavicchio <at> emc.com wrote:
> Unless I'm misunderstanding, this is the purpose of the <replaceable> element.

Yes, that's exactly what I was looking for !

Thanks a lot for the quick reply,

        Stefan

--

-- 

      ...ich hab' noch einen Koffer in Berlin...

Gmane