Good news: new year and new additions to LfL

classic Classic list List threaded Threaded
12 messages Options
Reply | Threaded
Open this post in threaded view
|

Good news: new year and new additions to LfL

Alexey Eromenko
Hi all !

Happy year! new year and new documentation !
I decided to celebrate that by writing two small how-to's for LfL.

About: Swap Files and instant dd

Once I have my LfL account setup, I will commit.

-Alexey Eremenko.
---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Good news: new year and new additions to LfL

Thomas Schraitle-2
Hi Alexey,

On Monday 01 January 2007 18:34, Alexey Eremenko wrote:
>
> Happy year! new year and new documentation !

Same from me. :-)


> I decided to celebrate that by writing two small how-to's for LfL.
>
> About: Swap Files and instant dd
>
> Once I have my LfL account setup, I will commit.

Cool! :-)


Have fun! :-)
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: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Good news: new year and new additions to LfL

Alexey Eromenko
At last !

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

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.

What do you think about it?

-Alexey
---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Good news: new year and new additions to LfL

Thomas Schraitle-2
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: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Good news: new year and new additions to LfL

Alexey Eromenko
hi all !

> > 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 !

-Alexey
---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Good news: new year and new additions to LfL

Thomas Schraitle-2
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: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Good news: new year and new additions to LfL

Alexey Eromenko
Tom: I appreciate your feedback very much, and already integrated it
into my document- "Using Swapfiles", but before I proceed to other
documents I have a few questions:

1. Is there any ability to add author's email in the <author> section?
1.a. What is the correct syntax for email integration (so that it will
be clickable)?

2. what's the conceptual difference between <orderlist><listitem> and
<procedure><step>,
As it looks the same in html output?
---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Good news: new year and new additions to LfL

Alexey Eromenko
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: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Good news: new year and new additions to LfL

Rebecca Walter
In reply to this post by Alexey Eromenko

> 2. what's the conceptual difference between <orderlist><listitem> and
> <procedure><step>,
> As it looks the same in html output?


The intention is that procedure is for something the reader should do and
order is for anything else that happens in a certain order.  They may look
the same now, but they don't have to look the same.  The style sheet
controlling the appearance right now is a really basic one.  But a different
one could differentiate them.  If I remember correctly, the one used on
internally prodcued books does give them different looks.


Unfortunately I can't answer your other questions.
---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Good news: new year and new additions to LfL

Thomas Schraitle-2
In reply to this post by Alexey Eromenko
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>[hidden email]</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>[hidden email]</email>. (By the way, you can also use
it inside a para.)
The standard stylesheets render it as <[hidden email]>. 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: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Good news: new year and new additions to LfL

Thomas Schraitle-2
In reply to this post by Alexey Eromenko
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&search=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 "&amp;".

The corrected url is:
"http://youtube.com/results?search_query=looking+glass+3d&amp;search=Search"

(Of course it will be rendered as you wrote above.)

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: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Good news: new year and new additions to LfL

Frank Sundermeyer
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 "&amp;".

BTW: The same would be true for HTML as well. As with HTML, too, you
also need to escape the following characters:

&lt; < less than
&gt; > greater than
&apos; ' apostrophe
&quot; " quotation mark

Instead of

&quot;text&quot;

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: [hidden email]
For additional commands, e-mail: [hidden email]