DOCBOOK: Re: linuxdoc to docbook migration

[Norman Walsh <ndw at nwalsh dot com>]

/ Douglas du Boulay <ddb@R3401.rlem.titech.ac.jp> was heard to say:
| An XTAL example of mine. There is a subprogram ADDREF which works 
| with irel, frel or f2rl data. "frel" is the default data type so the two commands 
|
| ADDREF 
| and
| ADDREF frel
|
| work identically.
| I would like a <command> notation that reflects that "frel" is a 
| default/redundant/built-in option, which could ultimately be rendered in some
| special font/face/colour/type. 

I'm not familiar with XTAL, but my first attempt would be something like this:

<cmdsynopsis>
<command>ADDREF</command>
<arg choice="opt">frel</arg>
</cmdsynopsis>

If you need to make a further distinction between optional and default, I think
I'd use role:

<cmdsynopsis>
<command>ADDREF</command>
<arg choice="opt" role="default">frel</arg>
</cmdsynopsis>

| A unix man page example. The command 
| enscript -1 ....
| creates a postscript file from a text file with 1 column per page.
| The option "-1" is redundant, being the default (between -1, -2 ... . 
| But is there a <command> tag wich denotes "-1"  as the  default optional argument?

In UNIX man pages, the command synopsis doesn't usually try to make
the distinction between optional and default.

|> |     (ii) I also had to abuse the  [] notation to get greek symbols in 
|> |         the body of the text e.g. [&alpha;] .
|> 
|> I'm not sure what you mean by [] notation.
|
| Sorry I mean the <f></f> inline formula notation - (remapped as [])

Oh, right, I forgot how much shortref was used.

| To change it to "F<superscript>2</superscript>" I have lost information.
| To go to 20 lines of MathML markup for each instance seems an incredible 
| amount of overkill. 

I suggest <phrase role="formula">F<superscript>2</subscript></phrase>
as a workaround until something more appropriate is available.

| What is the absolute minimum amount of <inline-equation>.. info needed to
| get an italic superscript text representation for such a simple notation?

Today, the inline equation element expects MathML or a graphic.

| And are there any problems with just dropping the odd iso-entity &alpha; 
| into the body of the text

Nope. Well, not from DocBook's point of view, anyway. Getting your
favorite renderer to "do the right thing" might be more challenging
for some of the less common symbols.

| How do the "professionals" deal with this? Has Docbook never been used by 
| O'Reilly to publish scientific texts? I thought that was the whole point?

DocBook's domain is computer software and hardware documentation. I
don't know how often it's been used to typeset scientific texts. Now,
that said, you've got a piece of software with heavily scientific
documentation, which is at least uncommon.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | Man's great misfortune is that he
http://www.oasis-open.org/docbook/ | has no organ, no kind of eyelid or
Chair, DocBook Technical Committee | brake, to mask or block a thought,
                                   | or all thought, when he wants
                                   | to.--Val\'ery