Re: Docs: Explain the types of DITA topics used in Derby documentation

[Kim Haase <Ca...@Sun.COM>]

Laura Stewart wrote On 10/30/06 17:16,:
> On 10/30/06, Laura Stewart <sc...@gmail.com> wrote:
> 
>>We need to decide just how many DITA tags the Derby documentation
>>should use.  There are dozens of tags that writers will be very
>>familiar with, but do we really want to encumber an open source
>>community with using all of those tags.
>>
>>I think that to encourage more people to write documentation in DITA
>>that we need to highlight the most important tags for them to become
>>familiar with.
>>
>>Please take a look at the updated Derby Documentation web pages, specifically
>>http://db.apache.org/derby/manuals/guidelines.html and the DITA Source pages.
>>The Writing Guidelines page is new.  I would like to list the most
>>essential tags people might want to know... the ones that we want to
>>encourage people to use consistently when updating existing topics.
>>The templates will show them the tags (mostly) that they need when
>>creating new topics, so I don't want to necessarily repeat all of
>>those tags.
>>
>>I'm thinking that we highlight the "top ten" most commonly used tags.
>>What would be on your top ten list?
>>
>>--
>>Laura Stewart
>>
> 
> 
> 
> BTW - According to OASIS
> http://docs.oasis-open.org/dita/v1.0/langspec/pre.html
> 
> pre
> The preformatted element (<pre>) preserves line breaks and spaces
> entered manually by the author in the content of the element, and also
> presents the content in a monospaced type font (depending on your
> output formatting processor). Do not use <pre> when a more
> semantically specific element is appropriate, such as <codeblock>.

This is a useful description. So is the description of <codeblock>,
which, the spec says, "represents lines of program code." This is a
fairly narrow definition, like the definitions of <msgblock> or
<syntaxdiagram>, which still leaves <pre> as a useful element for things
that don't fit any of those categories (a sequence of commands and
output, for example).

Sorry I haven't replied properly to your message yet. I've been thinking
about it, but I have two deadlines this week and haven't been able to
get to it!

Thanks,
Kim