Hi, On Friday 05 January 2007 22:41, Alexey Eremenko wrote:

At last !

I commited first series of How-Tos to LfL ! ! ! !

Congratulations! And it's all valid! :-))

The only problem is that I get a strange email each time I use "svn commit" It says: "Post by non-member to a members-only list" - admin check required.

It means, your commit mails needs approval by an administrator (me). Your changes has been committed successfully though. I am not very familiar with mailman, but I have approved the mails (see archive.) You shouldn't get any of this pestering mails anymore. Let me know if you still get them. Bye, Tom -- ---------------------------------------------------------------------- SUSE LINUX Products GmbH >o) Documentation Team Maxfeldstrasse 5 /\\ Technical Editor 90409 Nuernberg, Germany _\_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

Hi, On Saturday 06 January 2007 00:14, Alexey Eremenko wrote:

...

...

I commited first series of How-Tos to LfL ! ! ! !

I would be happy if someone could look at them and tell me how are they!

That's a good start! I had a quick look at the XML code, unfortunatly I haven't had the time to look at the text. You can improve your code by changing it slightly. I would like to suggest to use the following (used howto-swapfile.xml to describe it): 1. Use orderedlist instead of manually insert your numbers in a para. This gives you the advantage of automatically generated numbers and it doesn't break if you move, add ore delete one. Instead of: <para>1. You want to frequently change the swap-size; or</para> <para>2. Just save you from extra entries in partition table;...</para> <!-- ... ---> Replace it with: <orderedlist> <listitem> <para>You want to frequently change the swap-size; or</para> </listitem> <listitem> <para>Just save you from extra entries in partition table;...</para> </listitem> <!-- ... ---> </orderedlist> 2. Use element screen when a user sees or might see text on a computer screen. Instead of: <para> # dd if=/dev/zero of=swapfile.img bs=$[1024*1024*256] count=1 </para> Replace it with (in one line): <screen># dd if=/dev/zero of=swapfile.img bs=$[1024*1024*256] count=1</screen> 3. Describe commands in your paragraph with the command element: <para>Understanding the command "dd" ... </para> Replace it with: <para>Understanding the command <command>dd</command> ... </para> 4. Use xrefs instead of hardcoded text. Like the orderedlist, this has the advantage it doesn't break if you move, delete or add steps. You have to add an id attribute in your listitem, like this: <listitem id="li.swap.swapsize"> <para>You want to frequently change the swap-size; or</para> </listitem> To use it, use <xref linkend="..."/> and point to your previous id. Instead of: <para>Understanding the command "dd" from step 1 ...</para> You write: <para>Understanding the command <command>dd</command> from <xref linkend="li.swap.swapsize"/> ...</para> Voila! I think you got the idea. :-) Next time I will have probably more time to look at your text. Best wishes, Tom -- ---------------------------------------------------------------------- SUSE LINUX Products GmbH >o) Documentation Team Maxfeldstrasse 5 /\\ Technical Editor 90409 Nuernberg, Germany _\_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

Another problem that I just came across is and sign"&": <!-- I'we got a serious problem here, the interpreter intercepts "&" sign within a URL, effectively preventing me from using any search engime results. <para> Nice demo videos: <ulink url="http://youtube.com/results?search_query=looking+glass+3d&search=Search"/> </para> --> Any ideas? --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org

On Monday 08 January 2007 13:11, Thomas Schraitle wrote: Hi,

On Monday 08 January 2007 03:24, Alexey Eremenko wrote:

...

Another problem that I just came across is and sign"&":

<!-- I'we got a serious problem here, the interpreter intercepts "&" sign within a URL, effectively preventing me from using any search engime results. <para> Nice demo videos: <ulink url="http://youtube.com/results?search_query=looking+glass+3d&searc h=Se arch"/> </para>

This is one of the specialities of XML. ;-)

The '&' (ampersand) character is reserved for entities. If you want to have a single ampersand, you have to escape it by using "&".

BTW: The same would be true for HTML as well. As with HTML, too, you also need to escape the following characters: < < less than > > greater than ' ' apostrophe " " quotation mark Instead of "text" the preferred method with DocBook would be <quote>text</quote>. -- Tschau Frank -- Frank Sundermeyer, SUSE LINUX GmbH, Maxfeldstr. 5, D-90409 Nuernberg Tel: +49-911-74053-0, Fax: +49-911-7417755; http://www.suse.de/ Reality is always controlled by the people who are most insane Dogbert --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org

Hi Alexey, On Monday 08 January 2007 01:01, Alexey Eremenko wrote:

[...] 1. Is there any ability to add author's email in the <author> section?

Yes, use: <author> <firstname>Alexey</firstname> <surname>Eremenko</surname> <email>al4321@gmail.com</email> </author> See http://www.docbook.org/tdg/en/html/author.html for a more verbose example.

1.a. What is the correct syntax for email integration (so that it will be clickable)?

It's only <email>al4321@gmail.com</email>. (By the way, you can also use it inside a para.) The standard stylesheets render it as <al4321@gmail.com>. The text itself is clickable of course (a "mailto:" scheme is automatically inserted.)

2. what's the conceptual difference between <orderlist><listitem> and <procedure><step>,

Good point! :-) To answer your question: There is a *semantic* difference. Rebecca noted already some points. I just want to highlight the official definitions, according to "DocBook: The Definitive Guide": procedure: A list of operations to be performed in a well-defined sequence orderedlist: A list in which each entry is marked with a sequentially incremented label Although it looks the same in HTML and PDF, it doesn't mean it will be in the future too. For example, according to the layout spec for our openSUSE manuals a procedure is rendered with bold numerals. An orderedlist has just normal style. It would be impossible to apply these different looks if we would use ordinary orderedlists only.

As it looks the same in html output?

At the moment yes. But it's always good to be prepared for the future, isn't it? ;-) Bye, Tom -- ---------------------------------------------------------------------- SUSE LINUX Products GmbH >o) Documentation Team Maxfeldstrasse 5 /\\ Technical Editor 90409 Nuernberg, Germany _\_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