Re: DAVENPORT: Re: New docbook2man-spec.pl patches

[Norman Walsh <ndw@nwalsh.com>]

/ Steve Cheng <elmert@ipoline.com> was heard to say:
| On Tue, 10 Aug 1999, Norman Walsh wrote:
| 
| > I don't agree, exactly. It should have nothing to do with the filename.
| > There are four pieces of information that can come into play:
| > 
| >   refentrytitle
| >   refdescriptor
| >   refname
| >   manvolnum
| > 
| > If a RefEntry has a refentrytitle, that should be used, otherwise the
| > refdescriptor should be used, if it has one, and failing both of those,
| > the first refname should be used.
| 
| Are these some sort of 'authoritive' processing expectations?

Well, it's not like there's some sort of conformance test. Anything that
your stylesheets do that produces the output you want is perfectly fine,
but if you want to share your documents with others, it's a good idea
to have common processing expectations.

The expectations that I outlined above are the ones that I think are
most common. (I'd be delighted to hear from anyone who disagrees.)

| Because I don't agree with the "use first refname" --
| it should use ALL refnames.  And in some situations I want refnames to
| override refentrytitle.  Here's why:

That's an interesting point. I can see how you'd want that for TOCs,
but what about for xrefs? (Anyone else out there with lots of man pages
have any comment about how xrefs are handled? Eduardo? Bob? Micheal?)

| > So the xref to the refentry above should be "this page", or "this page(1)"
| > if it has a manvolnum.
| 
| I don't know of any manpages that don't have a section, i.e. manvolnum,
| so I think it should have a user-specified default manvolnum if not
| specified.

That would a perfectly reasonable local customization, but since
manvolnum is not required (and there are countless people using
refentry for things that aren't quite manpages), I don't think
it would be an appropriate standard expectation.

| > However, since you've provided an endterm on xref, it must resolve to
| > simply "this page".
| 
| Does it?  Is something like:
| 
| : this page [manpage(1)]
| 
| where the stuff in brackets is the actual xref acceptable?

Asking if something is acceptable is getting back into that gray area.
The processing expectations of xref are fairly specific. If the endterm
is supplied, the content of the element pointed to by endterm is used
as the cross reference text. You're suggesting something else, and that's
fine for your implementation, but if you exchange documents with others,
they may not have the same expectations.

| > Then you shouldn't be pointing to it with endterm! :-)
| 
| The whole confusion started because of a simple bug in docbook2man and
| user thought that was a feature :)

That's a new wrinkle. Usually it's the developers that want to make
bugs into features :-)

                                        Cheers,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | Entropy isn't what it used to be.
http://www.oasis-open.org/docbook/ | 
Member, DocBook Editorial Board    |