db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Andrew McIntyre" <mcintyr...@gmail.com>
Subject Re: "Working with Derby" conrefs file question
Date Thu, 07 Sep 2006 16:54:54 GMT
On 9/7/06, Laura Stewart <scotsmatrix@gmail.com> 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

Mime
View raw message