db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Laura Stewart" <scotsmat...@gmail.com>
Subject Re: Explanation of documentation file names (was :Re: How to commit documentation patches?)
Date Tue, 15 Aug 2006 09:07:10 GMT
Hi Kristian -

Answers below...

On 8/15/06, Kristian Waagan <Kristian.Waagan@sun.com> wrote:
> Laura Stewart wrote:
> > As someone who has recently started to make contributions to the Derby
> > docs, I have found a few "holes" in what is written on that page.
> > After 10.2, I plan to make some updates to it, including proposing
> > some standards, and an explanation of the file names (yes they are
> > confusing :-)
> Hello Laura,
> I'm planning to take on a documentation task, which involves converting
> HTML files to the DITA XML format. I'm getting ready for that now, but I
> too don't understand the naming of the source files.
> There seems to be some prefixes:
>  * 'c', 'r' and 't'.
>    Not quite sure what these are.

*** (LS) These refer to the type of topic - concept, reference, and
task.  Unfortunately there aren't any guidelines formally posted on
the Derby site as to the content for these.  After 10.2 I hope to
propose some guidelines that we can all follow... if you need some
help before that time, just ask :-)

>  * 'dev', 'tools', 'tuning', 'ref'
>    These indicate which manual the file belongs to.

*** (LS) Yes. That is correct.
> And, the great mystery, what do all the digits mean?
> Are they generated by a (deprecated) tool, are they random?
> For instance, 'rrefexcept71493.dita'.

***(LS) I believe that these file names were generated when the
documentation was converted to DITA.  That is before my time :-)
What I have adopted as a naming convention is to try to use general terms.
For example, I recently documented some new math functions.
Some of the existing names had numerical endings and some had the word
"func" at the end.  The problem with putting "func" at the end is that
the files are then scattered all over the place.  Instead I put the
"category" of info earlier in the name, so that the functions are all
together (at least the new ones that I added).
So I used the following:
r = reference topic
ref = Reference Manual
func = function
xxx = is the name of the actual function (sometimes abbreviated) and
it should unique

One of the functions was FLOOR, so the file name is rreffuncfloor.

> Can anyone please explain the naming scheme used for documentation
> source files?

*** (LS) I hope that this helps.  There isn't a limitation in the
number of characters that you can use in a DITA file name... the names
should be unique. I use the xxx
to make the names unique.

Laura Stewart

View raw message