> | My documents have
> | <refentry id="re">
> | ...
> | <refentrytitle id="re-title">
> | this page
> | </refentrytitle>
> | ...
> | and
> | <xref linkend="re" endterm="re-title">
> | Now, My understanding, developed from years of casual and occasionally
> | attentive reading of man pages, is that cross references always refer
> | to the name of the man file, using the convention filename(section),
> | where the file is actually named filename.section (modulo a qualifier
> | on the section field). So in this case, I process this using
> | v1.17+patches and "--section 1" option and
> | See <xref linkend="re" endterm="re-title"> for more information.
> | becomes
> | See this_page(1) for more information.
> I don't agree, exactly. It should have nothing to do with the filename.
OK...
> 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.
> So the xref to the refentry above should be "this page", or "this page(1)"
> if it has a manvolnum.
OK, but I have questions about manvolnum. I'm generating man page
output from generic makefile rules. I was worried about a couple of
things:
1) the manvolnum will determine part of the name of the output file.
If there is a mismatch between that and the makefile rule which was
invoked, then the file will be lost. Forcing it from the command line
during file generation seemed to be more robust.
2) the manvolnum might affect output for other output formats. I'll
experiment...
> However, since you've provided an endterm on xref, it must resolve to
> simply "this page".
Oh! I recall that I had to use an endterm to get good behavior for
html and postscript, but I'll go back and try again.
> | > >From DocBook reference: Processing Expectations:
> | > "XRef must have a Linkend, but the Endterm is optional. If it is used,
> | > the *content of the element* it points to is displayed as the text of the
> | > cross reference; if it is absent, the XRefLabel of the cross-referenced
> | > object is displayed. "
> | > See my emphasis. Content of element != file name of man page.
> | Does this make sense to you? I was assuming that cross references for
> | man pages would need to include the name of the target man page so
> | someone could actually find it. Text which does not correspond to the
> | man page name doesn't help, right?
> Then you shouldn't be pointing to it with endterm! :-)
> P.S. It might be a good idea to run this thread on the docbook list
> as well (still davenport@berkshire.net, but I'm trying to get it moved).
> There are a lot of people on that list with a lot of years of manpage
> experience.
Thanks for the clarification Norm! I'd settled on the xref attributes
a long time ago, since they gave correct behavior for the pages I was
generating from your style sheets, but I'll use your suggestions in
the future.
Steve, sorry for driving you nuts on trying to understand this. Do
Norm's suggestions match your preferences (they seem to line up with
what you said)? I'll back off trying to help with patches until I can
implement this more exactly.
I'd appreciate more clarifications and suggestions if folks have some,
though I think that this is a pretty complete explanation of what I
should be doing.
Regards.
- Thomas
--
Thomas Lockhart lockhart@alumni.caltech.edu
South Pasadena, California
