Explanation of documentation file names (was :Re: How to commit documentation patches?)

[Kristian Waagan <Kr...@Sun.COM>]

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.
  * 'dev', 'tools', 'tuning', 'ref'
    These indicate which manual the file belongs to.

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


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



Thanks,
-- 
Kristian

> 
> I am not a committer so I would need someone who is to help me
> understand the steps required for committing doc info so that I can
> write that up for the community.

Re: Explanation of documentation file names (was :Re: How to commit documentation patches?)

[John Embretsen <Jo...@Sun.COM>]

Kristian Waagan wrote:

> There seems to be some prefixes:
>  * 'c', 'r' and 't'.
>    Not quite sure what these are.

These are explained here:

http://db.apache.org/derby/manuals/dita.html#DITA+file+names

"All DITA topics are classified as either concepts, tasks, or reference 
material. Thus, every file begins with either a "c", "t", or "r". In 
addition, the letters that appear immediately after this first one 
provide a shorthand id for the manual. For example, the Getting Started 
with Derby manual uses "gs", so a reference topic DITA file in that 
manual will start with "rgs"."

>  * 'dev', 'tools', 'tuning', 'ref'
>    These indicate which manual the file belongs to.
> 
> And, the great mystery, what do all the digits mean?
> Are they generated by a (deprecated) tool, are they random?
> For instance, 'rrefexcept71493.dita'.

On the same web page, I found:

"Subsequent letters in the file name may provide hints at the topic's 
section within the manual, as well as numbers distinguishing it from 
other DITA files."

It seems that the numbers are random, but perhaps someone with DITA- or 
relevant historical knowledge has more details...


-- 
John

Re: Explanation of documentation file names (was :Re: How to commit documentation patches?)

[Laura Stewart <sc...@gmail.com>]

Hi Kristian -

Answers below...

On 8/15/06, Kristian Waagan <Kr...@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