LfL RFC

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

LfL RFC

Rebecca Walter
I've been working on the one section in LfL--the basic network server config.

I'd really like some feedback.  Does it look like what we want LfL to be?  
Does it make sense?  Is there anything else I ought to trouble shoot?

Also, about the structure.  Right now it is in a sysadmin section.  I'm
wondering if maybe we should make System Administration a part so we can have
more chapters in there.  Like one for Networking.

Comments anyone?

Thanks!
Rebecca
---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: LfL RFC

Alexey Eromenko
On 12/20/06, Rebecca Walter <[hidden email]> wrote:

> I've been working on the one section in LfL--the basic network server config.
>
> I'd really like some feedback.  Does it look like what we want LfL to be?
> Does it make sense?  Is there anything else I ought to trouble shoot?
>
> Also, about the structure.  Right now it is in a sysadmin section.  I'm
> wondering if maybe we should make System Administration a part so we can have
> more chapters in there.  Like one for Networking.
>
> Comments anyone?
>
> Thanks!
> Rebecca

In order to comment, I need to see your docs.
Plz give me link.
---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: LfL RFC

Tanja Roth
In reply to this post by Rebecca Walter
Hi Rebecca,

On Wednesday 20 December 2006 11:00 Rebecca Walter wrote (shortened):

> Also, about the structure.  Right now it is in a sysadmin section.  I'm
> wondering if maybe we should make System Administration a part so we can
> have more chapters in there.  Like one for Networking.

I think parts would be a good idea - at least as soon as we have more content
in the book (not necessarily now). Although...adding parts now would probably
reduce the need for restructuring later (when more chapters or sections would
be affected by this).

What do the others think?

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

Reply | Threaded
Open this post in threaded view
|

Re: LfL RFC

Thomas Schraitle-2
In reply to this post by Alexey Eromenko
Hi Alexey,

On Wednesday 20 December 2006 17:03, Alexey Eremenko wrote:
> On 12/20/06, Rebecca Walter <[hidden email]> wrote:
> [...]
>
> In order to comment, I need to see your docs.
> Plz give me link.

The DocBook XML source is here:

https://forgesvn1.novell.com/svn/lfl/trunk/books/en/xml/homenetwork.xml

Bye,
Tom

--
Thomas Schraitle

----------------------------------------------------------------------
SUSE LINUX GmbH      >o)   Documentation Specialist
Maxfeldstrasse 5     /\\    
90409 Nuernberg     _\_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: LfL RFC

Alexey Eromenko
> > In order to comment, I need to see your docs.
> > Plz give me link.
>
> The DocBook XML source is here:
>
> https://forgesvn1.novell.com/svn/lfl/trunk/books/en/xml/homenetwork.xml

Unfortunately I dunno how-to open this format. It seems OO2 can't open that.
How do you open it?
---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: LfL RFC

Tanja Roth
On Wednesday 20 December 2006 17:19 Alexey Eremenko wrote:
> > The DocBook XML source is here:
> >
> > https://forgesvn1.novell.com/svn/lfl/trunk/books/en/xml/homenetwork.xml
>
> Unfortunately I dunno how-to open this format. It seems OO2 can't open
> that. How do you open it?

Any texteditor wil do: Emacs, vi, Kate..whatever you want!
---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: LfL RFC

Rajko M.
In reply to this post by Rebecca Walter
On Wednesday 20 December 2006 04:00, Rebecca Walter wrote:

> I've been working on the one section in LfL--the basic network server
> config.
>
> I'd really like some feedback.  Does it look like what we want LfL to be?
> Does it make sense?  Is there anything else I ought to trouble shoot?
>
> Also, about the structure.  Right now it is in a sysadmin section.  I'm
> wondering if maybe we should make System Administration a part so we can
> have more chapters in there.  Like one for Networking.
>
> Comments anyone?

Hi Rebecca,

I'm not sure what exactly was meant under "make System Administration a part"
My guess would be something like this:
System Administration (book or part of the book)
        Network Configuration (chapter)
                Home Network  (subchapter)
                        Network with Router
                        Network with Local Server (your article)
Is this what you meant.

BTW, how to give comments on used words. I've seen "stipulated by your ISP"
and mostly is used "provided", instead.

--
Regards, Rajko.
http://en.opensuse.org/MiniSUSE 
http://en.opensuse.org/Portal 
---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: LfL RFC

Rebecca Walter
Cool!  Lot's of feedback.  It is great for me to have feedback and editors
because I haven't written as much lately (usually I'm the editor) and I can
never look as critically at my own work as I can at others' work.

Also this is a somewhat technical topic and my method might not be the best
way to do it.  It seems to have worked okay on my systems at home, but I have
this fear that someone will find a huge security bug in it and I'd hate to be
offering this as a good way to do it if it were actually dangerous. ;-)


> I'm not sure what exactly was meant under "make System Administration a
> part" My guess would be something like this:
> System Administration (book or part of the book)
> Network Configuration (chapter)
> Home Network  (subchapter)
> Network with Router
> Network with Local Server (your article)
> Is this what you meant.

Right.  Toms can probably explain parts better than I can but that is
basically it.  A part is a bigger chunk than a chapter but smaller than a
book.  The internally-produced manuals have parts in them.

Right now System Administration is a chapter and my text is a sect1.  But
System Administration is a pretty broad topic, so this could easily turn into
a huge and unmanageable chapter depending on how many other topics are added.

It is a bit hard to make a good structure when we don't know exactly what the
content will be in the long run.  Right now if each text is made as a sect1,
they are pretty mobile.   But we probably want to get a better idea soon of
what we expect so we can work out a good structure and set it up so authors
can contribute more comfortably.



>
> BTW, how to give comments on used words. I've seen "stipulated by your ISP"
> and mostly is used "provided", instead.

You just tell me what you think. ;-)  You're right, stipulated isn't the best
wording.  How about assigned?

Thanks!
Rebecca
---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: LfL RFC

Alexey Eromenko
In reply to this post by Tanja Roth
On 12/20/06, Tanja <[hidden email]> wrote:
> On Wednesday 20 December 2006 17:19 Alexey Eremenko wrote:
> > > The DocBook XML source is here:
> > >
> > > https://forgesvn1.novell.com/svn/lfl/trunk/books/en/xml/homenetwork.xml
> >
> > Unfortunately I dunno how-to open this format. It seems OO2 can't open
> > that. How do you open it?
>
> Any texteditor wil do: Emacs, vi, Kate..whatever you want!

yes, but text-editor opens that without formatting it properly. It's
like opening HTML with text-editor.
Is there any software that opens it correctly ? (need user-friendly editor)
---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: LfL RFC

Thomas Schraitle-2
Hi Alexey,

On Thursday 21 December 2006 15:54, Alexey Eremenko wrote:

> [...]
> > > Unfortunately I dunno how-to open this format. It seems OO2 can't
> > > open that. How do you open it?
> >
> > Any texteditor wil do: Emacs, vi, Kate..whatever you want!
>
> yes, but text-editor opens that without formatting it properly. It's
> like opening HTML with text-editor.
> Is there any software that opens it correctly ? (need user-friendly
> editor)

Well, there is Emacs but some people don't like it. ;)

Apart from Emacs there is also jEdit. I think I saw a XML plugin that can
use DTDs too (I have to look at it first.)

KDE's Kate is also a good editor although it might not be the primary
target for XML. It can use a precompiled kind-of DocBook DTD.

See here more details:
  http://wiki.docbook.org/topic/DocBookAuthoringTools


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: LfL RFC

Frank Sundermeyer
In reply to this post by Alexey Eromenko
On Thursday 21 December 2006 15:54, Alexey Eremenko wrote:

Hi,

> On 12/20/06, Tanja <[hidden email]> wrote:
> > On Wednesday 20 December 2006 17:19 Alexey Eremenko wrote:
> > > > The DocBook XML source is here:
> > > >
> > > > https://forgesvn1.novell.com/svn/lfl/trunk/books/en/xml/homenet
> > > >work.xml
> > >
> > > Unfortunately I dunno how-to open this format. It seems OO2 can't
> > > open that. How do you open it?
> >
> > Any texteditor wil do: Emacs, vi, Kate..whatever you want!
>
> yes, but text-editor opens that without formatting it properly. It's
> like opening HTML with text-editor.
> Is there any software that opens it correctly ? (need user-friendly
> editor)

AFAIK there is no such thing as a WYSIWYG XML/DocBook editor (I guess
that's what you are looking for). If you would like to see the book in
print layout you will have to build a PDF, for online layout build the
HTML version.
Please see
http://developer.novell.com/wiki/index.php/Lfl/Lessons_for_Lizards_Quickstart
for how to do that. (Please don't be scared off by the length of this
document - it is almost all about installing the software and getting
the XML sources. Once you have done that, you only need two commands:
make <target> and an occasional svn up).

Regards
        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]

Reply | Threaded
Open this post in threaded view
|

Re: LfL RFC

Rajko M.
In reply to this post by Rebecca Walter
On Thursday 21 December 2006 01:22, Rebecca Walter wrote:
> Cool!  Lot's of feedback.  It is great for me to have feedback and editors
> because I haven't written as much lately (usually I'm the editor) and I can
> never look as critically at my own work as I can at others' work.
>
> Also this is a somewhat technical topic and my method might not be the best
> way to do it.  It seems to have worked okay on my systems at home, but I
> have this fear that someone will find a huge security bug in it and I'd
> hate to be offering this as a good way to do it if it were actually
> dangerous. ;-)

You have in house security guys that can tell much more about.
The home networks on this side of the big water are usually designed around  
routers or router+modem combos. Configuration is pretty straight forward and
has not much common with SUSE so it probably will not find place in first
articles in LfL, but eventually it has to be taken in consideration as some
configurations have to be explained as they are not intuitive at all.

> > I'm not sure what exactly was meant under "make System Administration a
> > part" My guess would be something like this:
> > System Administration (book or part of the book)
> > Network Configuration (chapter)
> > Home Network  (subchapter)
> > Network with Router
> > Network with Local Server (your article)
> > Is this what you meant.
>
> Right.  Toms can probably explain parts better than I can but that is
> basically it.  A part is a bigger chunk than a chapter but smaller than a
> book.  The internally-produced manuals have parts in them.

Thanks.

> Right now System Administration is a chapter and my text is a sect1.  But
> System Administration is a pretty broad topic, so this could easily turn
> into a huge and unmanageable chapter depending on how many other topics are
> added.

System administration is broad enough for the book, so raising it to the part
might not be enough, but as you said

> It is a bit hard to make a good structure when we don't know exactly what
> the content will be in the long run.  Right now if each text is made as a
> sect1, they are pretty mobile.   But we probably want to get a better idea
> soon of what we expect so we can work out a good structure and set it up so
> authors can contribute more comfortably.
>
> > BTW, how to give comments on used words. I've seen "stipulated by your
> > ISP" and mostly is used "provided", instead.
>
> You just tell me what you think. ;-)  You're right, stipulated isn't the
> best wording.  How about assigned?

Assigned, provided,
furnished (is a bit unusual, but still correct).
The stipulated is legal term.
Did I mention that http://www.wordsmyth.net is my favorite vocabulary.


--
Regards, Rajko.
http://en.opensuse.org/MiniSUSE 
http://en.opensuse.org/Portal 
---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: LfL RFC

Rebecca Walter

> You have in house security guys that can tell much more about.
> The home networks on this side of the big water are usually designed around
> routers or router+modem combos. Configuration is pretty straight forward
> and has not much common with SUSE so it probably will not find place in
> first articles in LfL, but eventually it has to be taken in consideration
> as some configurations have to be explained as they are not intuitive at
> all.

Yes, we probably do.  However, I was hoping the community would contribute a
bit. I will e-mail one of them and ask him to take a look if he has time.

Here in DK, I could get a router from my provider, but I don't in case I want
a special config at some point.  I also feel more confident with a Linux
product because I know fixes are released quickly if a new security hole is
discovered.  How do I know the producer of whatever router the ISP rents to
me is as quick with fixes?  Plus I want a server in my home network anyway
for sharing my printer, so this is much cheaper for me. ;-)  Of course other
configurations are possible and probably better suited for other situations
but this one seems to work for me.  The only "dangerous" thing I am doing at
this point that I know of is running my server on a system that also
functions as a desktop.  This means physical access is probably easier and
the system also gets used regularly for surfing the net, etc. (as a regular
user, of course), but I wanted to save energy and space by decreasing my
number of machines that run 24x7 or close to it.

Do most routers provide DHCP for DNS and IP addresses or is manual
configuration needed there?  My experience has been that unless you pay for a
really high speed line (I have one that is actual a business product because
I work home office regularly), you have to provide the router yourself.  
Isn't a router more expensive than an extra eth card and openSUSE?

> System administration is broad enough for the book, so raising it to the
> part might not be enough, but as you said

Yes, it would be reasonable to have an entire book devoted to sys
administration, but we don't know at this point that the community is going
to contribute enough lessons to warrant splitting the book.  Internally, we
have most sysadmin tasks in Reference, but the point of LfL is to allow the
community (this includes in-house people) to focus on more unusual or
specific situations than we have the possibility to include in our internal
documents.

LfL can also include texts about using apps that aren't considered "standard"
or aren't covered in the internal docu or more in-depth descriptions of a
specific task with an app.  So it isn't all sysadmin related.  

Unless I am wrong here, I think it is also possible to build only a portion of
the book, like just a chapter or maybe even a part.  Toms, is this true with
LfL?  Can a user build just an HTML or PDF of a part?  

If the book as one entity starts getting too large and complicated, we can
always consider splitting it or consider other possibilities like making it
possible to tag texts after the intended user level so someone could make a
book with only the texts aimed at their level included.  My understanding is
that this is technically possible but not implemented.  The sources can get
complicated if we start making these divisions within a text.  But Toms can
also explain this better.

> Assigned, provided,
> furnished (is a bit unusual, but still correct).
> The stipulated is legal term.
> Did I mention that http://www.wordsmyth.net is my favorite vocabulary.

I occasionally use less common words in my first draft without thinking about
it.  I use the online Merriam Webster as my first point for quick checks, but
if I want stuff beyond that, I tend to refer to one of my reference books.  
But maybe it would be a good idea to add a list of useful online references
somewhere in the LfL project wiki?


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

Reply | Threaded
Open this post in threaded view
|

Re: LfL RFC

Thomas Schraitle-2
Hi,

On Wednesday 27 December 2006 11:27, Rebecca Walter wrote:
> [...]
> Unless I am wrong here, I think it is also possible to build only a
> portion of the book, like just a chapter or maybe even a part.  Toms,
> is this true with LfL?  Can a user build just an HTML or PDF of a part?

You are right, Rebecca. It is possible to build a chapter, appendix, part
or the whole book:

1. To build to whole book:
  make pdf

2. To build the chapter only with an id=foo:
  make ROOTID=foo pdf

(Same rules applies for HTML.)

However, at the moment it is not possible to build a PDF from a
single "lesson", because a lessons consist of sect1s. If I remember
correctly, the current stylesheets can not create a PDF from a single
sect1. You have to select the surrounding chapter. By the way, HTML is
not restricted.


> If the book as one entity starts getting too large and complicated, we
> can always consider splitting it or consider other possibilities like
> making it possible to tag texts after the intended user level so
> someone could make a book with only the texts aimed at their level
> included.  My understanding is that this is technically possible but
> not implemented.  The sources can get complicated if we start making
> these divisions within a text.  But Toms can also explain this better.

I will try it. :)

You are right, Rebecca. Of course, it would be possible to include all the
bells and whistles that DocBook provides. However, our intention was to
make it as easy as possible.

To provide some technical background from Rebecca's example you could add
on every sect1 (lesson) the attribute "userlevel". This attribute gives a
hint of how difficult is this lesson. It can have any of the
values "easy", "medium" or "difficult".  With the help of our XML build
mechanics it is possible just to render the "easy" lessons. Or
the "medium" ones. Or for experts the "difficult" lessons. Or create a
book with everything in it.

DocBook provides more of these features. However, you have to be careful
not to overuse it. For the start we choose a very simple approach.
BUT: From my perspective, it's better to have content (lessons) than to
take care of these technical details. These details can be discussed and
implemented later. We need content! :-)



> > [...]
> > Did I mention that http://www.wordsmyth.net is my favorite
> > vocabulary.
>
> I occasionally use less common words in my first draft without thinking
> about it.  I use the online Merriam Webster as my first point for quick
> checks, but if I want stuff beyond that, I tend to refer to one of my
> reference books. But maybe it would be a good idea to add a list of
> useful online references somewhere in the LfL project wiki?

Yes, please. :-) Maybe a page "Help for Contributors"?


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]