[opensuse-doc] LfL RFC

Rebecca Walter

20 Dec 2006 20 Dec '06

10:00

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: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org

Show replies by date

Alexey Eremenko

20 Dec 20 Dec

16:03

On 12/20/06, 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?

Thanks! Rebecca

In order to comment, I need to see your docs. Plz give me link. --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org

Thomas Schraitle

16:09

Hi Alexey, On Wednesday 20 December 2006 17:03, Alexey Eremenko wrote:

...

On 12/20/06, Rebecca Walter 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: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org

Alexey Eremenko

16:19

...

...
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: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org

Tanja

16:25

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: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org

Alexey Eremenko

21 Dec 21 Dec

14:54

On 12/20/06, Tanja 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: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org

Thomas Schraitle

15:43

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: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org

Frank Sundermeyer

20:48

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

...

On 12/20/06, Tanja 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_Quickstar... 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: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org

Tanja

20 Dec 20 Dec

16:07

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: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org

Rajko M.

21 Dec 21 Dec

01:20

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: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org

Rebecca Walter

07:22

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: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org

Rajko M.

22 Dec 22 Dec

00:37

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: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org

Rebecca Walter

27 Dec 27 Dec

10:27

...

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: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org

Thomas Schraitle

17:19

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: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org

6337

Age (days ago)

6344

Last active (days ago)

List overview

Download

13 comments

6 participants

participants (6)

Alexey Eremenko
Frank Sundermeyer
Rajko M.
Rebecca Walter
Tanja
Thomas Schraitle