Hi Alexey, On Dienstag, 30. Januar 2007, Alexey Eremenko wrote:

On 1/29/07, Alexey Eremenko <al4321@gmail.com> wrote:

...

Hi susers !

Good news: All my articles in LfL updated to match SUSE Documentation Style Guide. (announced earlier today by Rebecca Walter)

It took me just a few hours of work to read and accomplished those recommendations. I already commited the updated versions, so you judge the "successfullity" of my undertaking.

-Alexey Eremenko "Technologov"

So what do you think?

Thanks for all your good articles, Alexey! I was busy in the last days so I hadn't had the time to look at your files as I wished. I have only some small suggestions, others may have additional comments (hope it doesn't sound to harsh or picky): * Try to use more procedures, if applicable. Procedures tell your readers what they have to do actually. Be precise as possible. Start with a verb. For example, in file "lg3d.xml" you have this step: 1. First, you must get LG3D from their site: https://lg3d.dev.java.net/lg3d-getting-started.html as it is not included with openSUSE. Choose "binary mega-bundle" for Linux, x86. It includes Java6, Java3D and LG3D and weigths at about 150 MB What do you think about this? 1. Download the LG3D from https://lg3d.dev.java.net/lg3d-getting-started.html. It is not included in openSUSE. 2. Choose "binary mega-bundle" for Linux, x86. It includes Java6, Java3D and LG3D (around 150 MB). * Omit quotes, if possible. I mean, the directly inserted one, like "this". From a typographical point of view this looks ugly and it depends on the language. Use always <quote>this</quote>. You get the advantage it is fully localizable. In English you get “this”, in German „this“ etc. depending on the language. * Think about quotes again. Maybe the element command is better suited? :) For example, if you talk about the "dd" command, better insert in your XML code <command>dd</command>. * What do you think about lists in the "For more information" section? Depending on whether you want to explain the links or just want to list them, you can use variablelist or itemizedlist. An example for the first may looks like this: <variablelist> <varlistentry> <term><ulink url="http://www.example.com"/></term> <listitem> <para>Insert your description here...</para> </listitem> </varlistentry <!-- Insert more entries here --> </variablelist> An example for the second one looks like this: <itemizedlist> <listitem> <para><ulink url="http://www.example.com"/></para> </listitem> <!-- Insert more entries here --> </itemizedlist> * Yesterday I created an RPM package of xmlformat. This is a Perl or Ruby script that can be applied to any XML files to get consistent indentation. Few minutes ago I commited a configuration file for xmlformat in common/config. You can run it with: $ .../lessons4lizards/trunk/books/en> xmlformat.pl \ --config-file ../../common/config/docbook-xmlformat.conf \ xml/howto-swapfile.xml The above command prints an indented version of your XML file to standard out. If you want to replace it, add the additional option --in-place. Search for help with "--help". With xmlformat XML files are more legible and it's more consistent. What do you think about this? :) I have concentrated more on technical and structural issues. Probably Rebecca will answer the styleguide part. Keep up the good work! :-) Hope this helps, Tom ---------- [1] https://forgesvn1.novell.com/svn/lfl/trunk/common/xml/topic-template.xml [2] http://software.opensuse.org/download/home:/thomas-schraitle/openSUSE_10.2/ -- Thomas Schraitle ---------------------------------------------------------------------- SUSE LINUX GmbH >o) Documentation Specialist Maxfeldstrasse 5 /\\ 90409 Nuernberg _\_v http://en.opensuse.org/Documentation_Team --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org

...

* Omit quotes, if possible. I mean, the directly inserted one, like "this". From a typographical point of view this looks ugly and it depends on the language. Use always <quote>this</quote>. You get the advantage it is fully localizable. In English you get "this", in German „this" etc. depending on the language.

This is does not produce any warnings during "compile" time.

In addition, there is no "quotations" section in the SUSE docs style guide. I think we need to add one.

It isn't covered in the markup section? If not, we should definitely fix this. I will look into it. Thanks for the feedback! --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org