Re: DOCBOOK-APPS: Inquiry on inlines vs. sections of similar nature

[Bernd Kreimeier <bk@lokigames.com>]

Norman Walsh writes:
 > / Bernd Kreimeier <bk@lokigames.com> was heard to say:
 > | E.g. there seems no way to mark every occurence of 
 > | whateverFunc in a way that would (with proper stylesheet)
 > | render them identically. In other words, there is no
 > | match for e.g. <programlisting> or <funcname> that works
 > | inlined in regular text. You can use EnvVar to acocmplish
 > | matching appearance, but that's exactly the kind of abuse 
 > | you want to avoid. In reversal, a matching EnvSynopsis
 > | is absent as well.
 > 
 > I don't think I follow. You have a thing, a functionName() let's say,
 > and you want to render it inline sometimes and in a block at other
 > times and you want the appeance to be the same?

It's more than that. Say you have a blockquote, an entire
paragraph or two, that you dissect word by word, and
sentence by sentence, in the surrounding section. So there
will be bits and pieces of the blockquote littered throughout
the preceeding and following text. Having similar appearance
for the blockquote in its entirety and for any repeated
fragment is one possible way to emphasize the connection.
Another one (in a hypertext) is to turn every occurence of
a partial quote into a link to the full quote.

Let's say you have a FuncSynopsis on functA(). Now, in a
FuncSynopsis for FuncB() somewhere else it might be natural
to discuss and explain the function in terms like

  "FuncB() is always to be used in combination with FuncA(),
  but is mutually exclusive with use of FuncC()."

Again, in printed text an identical appearance of
repeated occurence of FuncX() might be a good tool.
In hypertext, a direct link to the respective synopsis
is even better. Let's say somewhere else in the book
you discuss an example/programlisting at great length,
step by step - every mention of funcA() and funcB()
should be marked in a way that points (visually or
hyperlinked) to the synopsis.

In the inverse: the EnvVar element provides the inline,
but there does not seem to be a matching EnvVarSynopsis.

There is an underlying pattern here. When I tried to
overhaul the Linuxdoc DTD (ages ago), I called it a
glossary+keyword combination. Maybe you can call it
"pars pro toto" - a writer using a shorthand for an
entire part of the document. Somewhere in the text there 
will be a definition/instantiation for an (abstract)
entity: call it synopsis, quote, example. All over the
surrounding document there will be mentions and references 
to this entity - so shorthand has become a keyword (or,
in your DTD, a GlossTerm?).

Linuxdoc DTD relied on an ASP based backend (single pass
textual replacement), so elements were really simplistic, 
somwhat like

   paragraph           inline

   <quote>              <q>                 italic
   <code>               <c>                 tt
   <keyword>            <k>                 bold

I also made some attempts to make these elements appear 
in the Index: e.g. that the paragraph instance would be 
marked as the main reference, and every other occurence 
could be listed as well, depending on an adjustable 
visibility attribute (vis=0|..|9).

Anyway, I found the "pars pro toto" relationship to be
a recurring theme in the documents I wrote, and would
like to know how to do appropriate markup DocBook. 
What I am looking for seems to be a GlossTerm
equivalent for elements like BlockQuote, FuncSynopsis,
as well as an equivalent to FuncSynopsis for inline
elements like EnvVar. Sounds reasonable? Maybe I should
wrap my brain around how you architected Glossary.

                                         b.