This is the mail archive of the docbook-apps@lists.oasis-open.org mailing list .


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: [docbook-apps] DocBook XSL 1.67.0 released


When I said that the default rendering of var was inappropriate
for programming variables and program arguments, I had in mind two
specific DocBook elements: varname and arg

In your original response, you suggested we use var for varname output.

But if we use var for varname, a CSS-less rendering will result in
varname being rendered in italic type. I don't think most people
want that. See the example in the reference page for varname -

  http://docbook.org/tdg/en/html/varname.html

Do people want to have @ARGV rendered in italic? Do we want to
_force_ them to change it via a CSS stylesheet if they don't?

And in the case of arg, the current stylesheets don't generate any
HTML markup for it all. If you're inclined to think arg should get
marked up with var, see the example in the cmdsynopsis ref page -

  http://docbook.org/tdg/en/html/cmdsynopsis.html

I don't think anybody wants the "-t" in "emacs -t file" to be
rendered in italic. And I don't think we want to force them to
change it via CSS if they don't want it that way.

Function and method arguments/parameters are a whole nother story.

There is actually one place in the current stylesheets that
generates var: paramdef/parameter.

Method arguments (methodparam) just generate 'span class="methodparam"'

Elliotte Rusty Harold <elharo@metalab.unc.edu> writes:

> At 4:12 AM +0900 11/12/04, Michael Smith wrote:
> 
> >The problem is that its default rendering makes it inappropriate
> >for marking up programming variables or program arguments -- which
> >most people do not want rendered in italic.
> 
> I'd question that statement. I *do* want method arguments rendered in 
> italic, at least a significant fraction of the time. This is the 
> convention I've used in several books, including XML in a Nutshell, 
> and I've seen it used in other O'Reilly books as well.
> 
> I agree not everyone wants this, nor does everyone want it all of the 
> time. I've also written books where I did not italicize method 
> arguments. However no one single convention will satisfy everyone. 
> This is what CSS is for. Different documents can choose different 
> renderings for var, as they like.
> 
> However, I am specifically not bothered by the default rendering of 
> var as italic. This is a common idiom, and a reasonable one.
> 

Attachment: smime.p7s
Description: S/MIME cryptographic signature


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]