On 9/7/06, Laura Stewart <[EMAIL PROTECTED]> wrote:
Hi -
In a comment on another book, the follow question was asked:
"There's one more question that I wonder if I should file a separate
bug for. The new book, workingwithderby, has a conrefs file that
doesn't include the "prod" settings that the other ones have. Instead
it just hardcodes "Derby" and "DERBY_HOME" and whatnot into the text
files. I don't know how important this is. If you think it's worth
doing, I can take it on. The books should probably be consistent."
I agree with this comment and think that the conref files should be
consistent for all of the Derby books. The conref files contain words
that are "common references" in many topics. The advantage of adding
words to the conrefs files is that when something changes, such as the
name of an environment variable, it ionly needs to be changed in the
conrefs files. The change is then automatic for all of the (often
dozens) of files that use that common term. Common words that might be
changed should be added to the conrefs files and not hardcoded into
the topics.
What do others think?
Definitely. I made a comment about this a little while ago, but it
would also be a good idea to consolidate the various conrefs files
into a single shared file at src/derbyconrefs.dita. Since conref
references are just URLs, pointing the location from inside the doc
tree to ../derbyconrefs.dita works just fine, and since the conrefs
are replaced by the content of the reference in the conref file, there
are no upward pointing URLs (i.e. no links to ../derbyconrefs.dita) in
the resulting build of the docs.
It will be a little more work to do that, since it would touch all of
the manuals and every file that uses conrefs, but I think it would be
worth it to have a single place to store this information, instead of
one for each manual.
andrew
