Hi Tony,
As Editor for the User Manual and Quick Guide, Subsystem responsible for
Documentation and Help (my official roles in the ArgoUML project), I feel
the need to comment on this.
Since my $%&# email program refuses to add "> " in front of replies, I will
quote some sentences from your mail:
"All titles of chapters, sections etc. are capitalized throughout … All
titles of figures, tables etc. have the first word only capitalized."
This is only for esthetical consistency - I do not bother too much - we have
bigger fish to fry.
"Make a new line after each sentence or before expressions.
The Docbook source is source that is handled by subversion.
When structuring the text the parts are paragraphs,
sentences and words.
By having each sentence on a line of its own it is easier to see which
sentences have been changed
and which have not in the |diff| reports from subversion.
The contributions that Jeremy Bennet did for the 0.10 User Manual are not
written like this.
Change it while changing the paragraphs."
I am not sure you understood this paragraph - so I reformatted it in the
intended way.
This rule has nothing to do with indenting.
The intention is to have at most one sentence per line. Start a new sentence
on a new line, or even break after a comma.
You do not mention indenting, which I would have expected.
Long ago, Linus started with indenting solely the opening xml tag, and not
the text. An example may clarify:
<para>
During save the persistence subsystem requests each subsystem for its
persistence data and adds that data to output it is collating.
</para>
<para>
During load the persistence subsystem unwraps the persistence data and
passes
these to the relevant subsystems for those subsystems to build themselves.
</para>
However, I never liked this indenting scheme, and used more classical
indenting:
<para>
During save the persistence subsystem requests each subsystem for its
persistence data and adds that data to output it is collating.
</para>
<para>
During load the persistence subsystem unwraps the persistence data and
passes
these to the relevant subsystems for those subsystems to build
themselves.
</para>
The cookbook describes it as follows:
"This does not apply to the manual any more
(it now uses standard formatting as supported by most xml editors):
Indent only the tags, not the text.
The Docbook source is kept in subversion that is a line-oriented tool.
This means that reindentation will be a major thing in subversion making
it hard to see if there were other things done to the code.
Especially if reindentation caused the paragraphs to be broken
in a different way.
Not indenting the text means that the text will be unchanged even
if the heading level was changed.
The contributions that Jeremy Bennet did for the 0.10 User Manual
are not indented like this.
Change it while changing the paragraphs."
IMHO, if you change the complete format of the document for docbook 5,
please follow the complete indenting!
Regards,
Michiel
----- Original Message -----
From: "Tony | "Zearin"" <[EMAIL PROTECTED]>
To: <[email protected]>
Sent: Thursday, January 10, 2008 12:25 PM
Subject: Re: [argouml-dev] Re: AW: MDA Flow in ArgoUML
I would love to take a look at that!
…But I DO want to at least finish my current task with documentation
first. Unfortunately I'm a little stuck on a few things:
1.
I'm a little embarrassed to admit it, but I'm still confused on
procedure.
Let me state what I do know: I have a branch that is a copy of the
current trunk, and I'm supposed to check it out. So then I have a
local working copy of the trunk, essentially (only difference
being that it's a copy and not the trunk itself). I also have the
documentation that I converted to DocBook 5 locally.
How do I "merge" (I'm using the word loosely) my own changes with
the working copy?
2.
When I was almost finished converting the documentation to DocBook
5, I read the part on indentation and tabs. I felt pretty sheepish
at that point, but I was still so excited to be participating in
open source I quickly got distracted again. But as this is my
first shared project ever, I've never had a reason to familiarize
myself with the features of my IDE that set the code formatting.
(I do now, of course! :)
Also, I have some comments on the following:
* From §8.3 Document Conventions
<http://argouml-stats.tigris.org/documentation/defaulthtml/cookbook/ch08s03.html>
:
o "All titles of chapters, sections etc. are capitalized
throughout … All titles of figures, tables etc. have
the first word only capitalized."
If preference for capitalization ever changes in the
future, these two rules will be troublesome.
Capitalization is best left "normal" in document
markup, and is most flexible when handled by a
stylesheet. Both XSL and CSS stylesheets have ways to
manipulate capitalization, and they do it with options
like /UPPERCASE/, /lowercase/, and /Capitalized Case/.
When you want to change a string to all one
case/capitalize every first character, it's simple.
However, this can be a real problem when there are
/methodNamesThatUseCamelCase/, or /Titles of Items
that only Capitalize very specific Words/.
The only way to keep the integrity of these occasional
(but important) scenarios is to use standard casing in
the markup and use XSL (for non-HTML) or CSS (for
HTML) stylesheets to fine-tune preferences for
uppercase titles, lowercase links, or what-have-you. :)
o "Use full URLs throughout all documents! Rationale:
These documents may also be published in other formats
than html on the ArgoUML web site."
This is something else I think is best handled by XSL.
I don't know what XSLT engine we're using, but if we
are not using XSLT 2.0 then I recommend Saxon 9
<http://saxon.sourceforge.net> (free). XSLT 2.0
provides tons of advantages over 1.0, one of which if
URI resolution. :)
* From §8.4 DocBook Conventions
<http://argouml-stats.tigris.org/documentation/defaulthtml/cookbook/ch08s04.html>
:
o "Make a new line after each sentence or before
expressions. The Docbook source is source that is
handled by subversion. When structuring the text the
parts are paragraphs, sentences and words. By having
each sentence on a line of its own it is easier to see
which sentences have been changed and which have not
in the |diff| reports from subversion. The
contributions that Jeremy Bennet did for the 0.10 User
Manual are not written like this. Change it while
changing the paragraphs."
This might make it easier to see the changes in the
text, but it actually made converting the markup from
v4 to v5 a nightmare. I tried to respect it for a
little while but before long I gave up and used the
auto-indent feature of my IDE.
I do admit--this convention is pretty strange for
someone who has been working with markup documents for
years, but never worked on a shared project before.
But I'll be glad to "re-introduce" this formatting
once I can get the documentation to build okay.
3. On a completely different note… Am I correct in thinking that the
sole purpose of AndroMDA is model transformation? Or does it
overlap with ArgoUML at all?
Thanks Linus. ;)
-- Tony | "Zearin"
Linus Tolke wrote:
Hello Tony!
There is a plugin called argouml-andromda that added some features to
ArgoUML allowing the start of AndroMDA from within argouml. Unluckily,
nobody has worked with it for a while so it doesn't work right now.
Perhaps you would like to have a look at that?
/Linus
--------------------------------------------------------------------------------
No virus found in this incoming message.
Checked by AVG Free Edition.
Version: 7.5.516 / Virus Database: 269.19.0/1216 - Release Date: 9/01/2008
10:16
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
