discuss: Thread: proposed outline: Author Guide

On Tue, Jul 08, 2003 at 07:03:45PM -0400, Emma Jane Hogbin wrote:
> On Tue, Jul 08, 2003 at 04:00:49PM -0700, Tabatha Marshall wrote:
> > Having done most of my growing up in Canada, I can honestly say that in
> > school we're taught to spell everything the "British" way...(like words
> > ending in "or": flavour, neighbourhood, colour).  
> 
> Except words like "program". I swear "programme" is a completely foreign
> word.

In the case of a computer program as opposed to a TV programme,
"program" is the normal spelling used by British English speakers too,
despite normally being American. Likewise "dialog box" and "disk".

There are a few holdouts who'll write about "computer programmes"
instead, but they're unusual.

Cheers,

-- 
Colin Watson                                  ####@####.####

Colin Watson wrote:

> In the case of a computer program as opposed to a TV programme,
> "program" is the normal spelling used by British English speakers too,
> despite normally being American. Likewise "dialog box" and "disk".

The major exception being "compact disc" [TM] :-)

On Thu, 10 Jul 2003, Glen Turner wrote:

> Colin Watson wrote:
> 
> > In the case of a computer program as opposed to a TV programme,
> > "program" is the normal spelling used by British English speakers too,
> > despite normally being American. Likewise "dialog box" and "disk".
> 
> The major exception being "compact disc" [TM] :-)

doubleplussgood.

Le Mardi 8 Juillet 2003 14:56, Emma Jane Hogbin a écrit :
> On Tue, Jul 08, 2003 at 09:50:36AM -0400, Mark Komarinski wrote:
> > On Tue, Jul 08, 2003 at 03:57:17PM +0930, Glen Turner wrote:
> [...]
> > > What would be really nice list a huge section listing
> > > all the markup templates
>
> I have mixed feelings on this. I think if there were an LDP style guide
> that says "this is how we recommend you make a ***" then it would be
> useful. If it's just going to be a huge table without descriptions and
> context I don't think it's any more or less useful than what DocBook has
> already done themselves.
>
This is what the KDE team does for their own documentation. See 
http://i18n.kde.org/doc/markup/index.html for more details.
Doing such a thing is really interesting IMHO 'cause DocBook has a really huge 
number of tags and lowering it a bit could be something interesting.

> I think it would be useful is to look at document components and
> explain them. For the "code" bits I would give rationale on why it's used
> this way. For the "before" stuff I would simply give a "this is how we do
> it" explanation. As an author I could also then use it as a checklist to
> make sure I had all of the correct bits (Tabatha had to re-write most of
> my "before" content because it wasn't in the right format, although it
> validated as DocBook).
> e.g. (much of this is already in the table listing)
> 	before: author info, dates, versions, copyright etc
> 	content: lists, paragraphs, sections, application
> 	asides: warning, note, tip
> 	commands: userinput, parameter, option
> 	display: screen
> 	references: sample of how to make a bibliography, link within a
> 		document
> 	after: license, appendix
>
> > A lot of this has already been done.  Either by purchasing DocBook: TDG,
> > or by looking at it online (http://www.docbook.org/tdg/en/).  When I
> > wrote the LAG, I didn't want to duplicate a lot of effort, mostly because
> > I'm lazy.
>
> Forget about the lazy factor! The DocBook web site is really easy to use!
> The elements are cross-referenced and tell you what other things you
> should consider that are similar; it tells you what an element must
> contain; and what it may be contained in; and it tells you the attributes
> you can use. What the DocBook is lacking is good descriptions of when to
> use the elements--it's a little too flexible perhaps.
>
And perhaps less tags?

When I translate a HOWTO in french, I always put it in xml docbook format. 
It's much easier to use with stylesheet.

Regards.


-- 
Guillaume <!-- http://absfr.tuxfamily.org/ -->.