discuss: Translation effort workflow
Subject:
Re: [discuss] Translation effort workflow
From:
David Lawyer ####@####.####
Date:
12 Oct 2005 08:44:01 -0000
Message-Id: <20051012084358.GB1623@lafn.org>
> On Sun, 9 Oct 2005, David Lawyer wrote:
>
> > I think that I took a very quick look as AsciiDoc some time ago and
> > concluded that it was not much easier than LinuxDoc (using a minimal
> > number of LinuxDoc tags). So since the existing docs are in
> > LinuxDoc/DocBook, they probably should be kept in those formats. I
> > would like to see LDP encourage the conversion of DocBook docs to
> > LinuxDoc for cases where a new author is taking over that is not
> > familiar with DocBook.
>
On Tue, Oct 11, 2005 at 10:48:05AM +0000, Machtelt Garrels wrote:
> For new authors, the format of their submission is not important. I can
> not stress this enough: authors should focus on content. We, at the back
> end, editors and the like, will take care of any conversion needed and
> make sure presentation of the content is ok. We should get over this
> docbook/linuxdoc/asciidoc/whateverdoc discussion because it frightens
> people. If a new author sends an HTML or a LateX file, or even an (Open)
> Office doc, that's fine.
It is important. For one, the author will need to understand the
markup in order to make additions and changes to the doc in the
future. The doc may need updating every couple of months. Also, when
a doc is submitted that has no section tags (or the like) how will the
person doing the conversion know where to put the section tags? It
would make life a lot simpler if the author used the section tags in
the submission (provided it's linuxdoc). Also, a writer that doesn't
know about section tags may not realize that the doc needs to be
divided up into sections and subsections. In addition, they may not
know about lists and will not use them when they should be used. How
will they designate the name they want to use for urls if they submit
it with no markup?
So I think that it's easier on the author to learn linuxdoc, say by
reading my howto on it or by using the howto generator, etc. If one
knows a little about html or xml, it's very easy to learn a minimal
set of linuxdoc tags. Learning it at first is preferable to learning
it later since it will save the time of the person doing the markup
conversion. And then the author will know how to update the doc.
There is really little to learn. For the header part one just copies
another doc and sees <title>, <author>, <date>, with no closing tags.
Filling this out is as simple as filling in To: and Subject: of
emails. Then there are the <sect>, <sect1>, etc. tags which one needs
to know to divide the doc into sections. And the title of the section
is written right after the section tag. Then there's the <item> tag
for each item of an itemized list and the <itemize> </itemize> tags
enclosing the list. Use double spacing for paragraphs and <p> for the
start of the first paragraph of a section. Then there's the url tag
with url= and name=. Also, there are label tags and ref tags so that
one can click on a ref and jump to a label. Then there's the
<article> tag pair enclosing the whole thing and a tag at the start to
say it's linuxdoc. As an afterthought, there's the <toc> tag to get a
table of contents generated.
How hard is all this to learn? If someone doesn't know about urls or
jumping to a label by clicking, then it may be hard to learn. But for
many authors it will be easy to learn. I thus think that it's easy to
get started writing an article in LinuxDoc. For DocBook, it may be a
few times more difficult. That why I think we should encourage people
to learn a minimal LinuxDoc and write their article in it. I think it
took me about an hour of so to get started with linuxdoc a long time
ago. I learned more than just a minimal set of tags and didn't have
them as macros in vim so I then had the burden of having to type the
tags.
David Lawyer
