- openSUSE Documentation

[opensuse-doc] KDE Booklet
by Javier Llorente 16 Dec '10

16 Dec '10

Hi list-mates, Some people at KDE (upstream) are almost done writing the official KDE Booklet. I have asked one of the authors what format they are using and he replied InDesign. Well, how could .po files be generated for an easier translation? I have never used InDesign. He also asked for alternatives. Luiz (elchevive) told me that Thomas (toms) recommended him http://www.syntext.com/products/serna-free/ (a free xml editor) a long time ago. Thanks, -- Javier Llorente

4 4

[opensuse-doc] questions for susedoc (Japanese fonts in susedoc)
by Yasuhiko Kamata 13 Dec '10

13 Dec '10

Hello all, We're now trying to translate the opensuse_manual to Japanese in beriOS.de (http://developer.berlios.de/projects/opensuse-man-ja/) This translation effort is about 25 percent completed. So I've planned to generate a PDF file from them. Before making, I've modified /usr/share/susedoc/xslt/common/l10n/ja.xml as follows for IPA fonts.  <l:gentext key="fop1.body.font.family" text="IPAPMincho,FreeSerif"/> <l:gentext key="fop1.sans.font.family" text="IPAPGothic,FreeSans"/> <l:gentext key="fop1.monospace.font.family" text="IPAGothic,FreeMono"/> <l:gentext key="fop1.symbol.font.family" text="IPAPGothic,Symbol"/> <l:gentext key="fop1.callout.unicode.font" text="IPAPGothic"/> ("fop1.pocket.*", "xep.*", and "xep.pocket.*" was also modified like above) After modification, run as follows. $ cd trunk/opensuse-html $ source ENV-opensuse-html $ make validate $ make pdf Validation (make validate) and PDF creation (make pdf) finished with no error. But some sorts of tagged texts in PDF were displayed with blank. These are "guimenu", "replaceable", and "xref" (referenced text). In addition, some characters of these texts can be displayed normally if the character is ASCII (alphabets, numbers, etc.). So I think this problem was caused by some font setting. However, no font settings seems to be exist in susedoc except above. How do I fix it? Cheers, -- Yasuhiko Kamata E-mail: belphegor(a)belbel.or.jp -- To unsubscribe, e-mail: opensuse-doc+unsubscribe(a)opensuse.org For additional commands, e-mail: opensuse-doc+help(a)opensuse.org

4 11

[opensuse-doc] KIWI and oBS missing from doc.o.o
by Javier Llorente 09 Nov '10

09 Nov '10

Hello everybody, I have just visited doc.o.o and I saw that links to KIWI and oBS docs aren't there. I suggest adding more fabulous manuals :-) http://git.berlios.de/cgi-bin/gitweb.cgi?p=kiwi;a=blob;f=doc/kiwi.pdf http://en.opensuse.org/Category:Build_Service this one is part of the wiki (no static content, not suitable for doc.o.o?) https://api.opensuse.org/apidocs/ I also think that there should be a link to doc.o.o or to the documentation portal in the wiki's main page (en.o.o). Documentation is very *important*. Greetings, -- Javier Llorente

2 1

[opensuse-doc] doc.opensuse.org title
by Manu Gupta 26 Oct '10

26 Oct '10

Hi all doc.opensuse.org still remains rtfm.opensuse.org at the website please correct that Regards Manu -- To unsubscribe, e-mail: opensuse-doc+unsubscribe(a)opensuse.org For additional commands, e-mail: opensuse-doc+help(a)opensuse.org

2 3

[opensuse-doc] [ANN] Documentation Sources Going Public (opensuse-doc)
by Thomas Schraitle 24 Oct '10

24 Oct '10

Hi, after some blood, sweat, and tears (actually it was only the middle, but hey, that statement sounds more dramatic! ;) our documentation sources are publicly available on BerliOS! :-) The opensuse-doc project[1] contains now all the sources for openSUSE including our business products released under the GFDL. It's possible to anonymously check it out; go to the SVN page[2] on our project page for more details. Alternativly, for a more visually attractive version of our SVN, use the WebSVN page[3]. The opensuse-doc SVN is the result of the merge of three different, independant SVN repositories. It has been merged before and during the openSUSE conference. 1. Want to contribute? Find more information in the openSUSE Wiki[4]. We are happy to discuss your contributions on our opensuse-doc mailinglist. 2. Want to know more about us? Find our team page on the openSUSE Wiki[5]. 3. Want an overview about what's inside our SVN? Find more information about our SVN structure here[6] There will be some fine tuning over the week -- expect still some changes, but not dramatically. Hope you like it! :) Tom ----- References: [1] http://developer.berlios.de/projects/opensuse-doc/ [2] http://developer.berlios.de/svn/?group_id=11522 [3] http://svn.berlios.de/wsvn/opensuse-doc/trunk/ [4] http://en.opensuse.org/openSUSE:Documentation_Contribute [5] http://en.opensuse.org/openSUSE:Documentation_team [6] http://en.opensuse.org/openSUSE:Documentation_Contribute#SVN_Structure -- Thomas Schraitle ---------------------------------------------------------------------- SUSE LINUX GmbH >o) Documentation Specialist Maxfeldstrasse 5 /\\ 90409 Nuernberg _\_v http://en.opensuse.org/Documentation_Team http://developer.novell.com/wiki/index.php/Lessons_for_Lizards http://lizards.opensuse.org/author/thomas-schraitle/ --------------------------------------------------------------------- -- To unsubscribe, e-mail: opensuse-doc+unsubscribe(a)opensuse.org For additional commands, e-mail: opensuse-doc+help(a)opensuse.org

1 0

[opensuse-doc] New (i hope so) Member of the Team
by Sascha 'saigkill' Manns 24 Oct '10

24 Oct '10

Hi Mates, as i talked with Jürgen Weigert and Thomas Schraitle i have interest to join the Team. I know the new Place of the Sources in Berlios, and i can use Serna and XML Mind (depends on that what i would like to do) and now the process to create the needed Output. So if you're meaning, that i can help out, just drop me a note :-) -- Sincerely yours Sascha Manns open-slx GmbH openSUSE Community & Support Agent openSUSE Marketing Team Blog: http://saigkill.wordpress.com Web: http://www.saschamanns.de Web: http://www.open-slx.de (openSUSE Box Support German) Web: http://www.open-slx.com (openSUSE Box Support English) Open-SLX : Linux convenient, simple, secure and complete

2 1

[opensuse-doc] Re: [opensuse-project] How to contribute: openSUSE Documentation
by Juergen Weigert 20 Oct '10

20 Oct '10

On Oct 18, 10 18:00:39 +0200, Freek de Kruijf wrote: > Op maandag 18 oktober 2010 17:07:47 schreef Juergen Weigert: > > This information should be in the wiki in separate pages, but with links to it > from Portal:Documentation and Portal:How_to_participate and Portal:Teams Right you are! Thanks for those pointers. I've taken the liberty and added my team to the portals. (And chopped the contents into 3 parts.) cheers, JW- -- o \ Juergen Weigert paint it green! __/ _=======.=======_ <V> | jw(a)suse.de back to ascii! __/ _---|____________\/ \ | 0911 74053-508 __/ (____/ /\ (/) | _____________________________/ _/ \_ vim:set sw=2 wm=8 SUSE LINUX Products GmbH, GF: Markus Rex, HRB 16746 (AG Nuernberg) "You are trying to use packages from project 'openSUSE:11.3'. Note that malicious packages can compromise your system." -- To unsubscribe, e-mail: opensuse-doc+unsubscribe(a)opensuse.org For additional commands, e-mail: opensuse-doc+help(a)opensuse.org

2 1

[opensuse-doc] How to contribute: openSUSE Documentation
by Juergen Weigert 18 Oct '10

18 Oct '10

Hi there! Last week a discussion started on opensuse-marketing about creating an openSUSE manual: http://lists.opensuse.org/opensuse-marketing/2010-09/msg00259.html While this is a cool idea, it turned out that many people are unaware of the existing openSUSE documentation or do not know how to contribute. Being responsible for the openSUSE documentation, I would like to shine a light on this ;-) : Table of contents (beware, lengthy posting): 1. Contributing 1.1 Getting in touch with the SUSE Documentation Team 1.2 Reporting Documentation Bugs or Suggesting Adjustments 1.3 Translating Manuals 1.4 Contributing new Chapters or Books 1.5 Contributing to the Build Environment (susedoc) 2. Outlook: What's in the Pipeline 2.1 Publishing the Book Sources 2.2 Re-writing the Build Environment 2.3 openSUSE BookBuilder 3. List of openSUSE Manuals ################### # 1. Contributing # ################### Currently the openSUSE documentation (listed below under 3.) is maintained mostly within Novell by the SUSE Documentation Team (http://en.opensuse.org/openSUSE:Documentation_team) The discussion on opensuse-marketing has shown that people are interested in contributing to this documentation--a fact that we really welcome! Our manuals are written in NovDoc XML, a simplified subset of DocBook (http://www.docbook.org/) The XML sources for the manuals are hosted on an SVN server. Generating books from the XML sources is done with the susedoc build environment, which is developed and maintained by the team as well. This build environment includes _everything_ to build books from DocBook or NovDoc and is shipped with openSUSE (package: susedoc, license: GPL). You may also want to point us to ommissions, corrections, or even to ready articles (wiki, txt, pdf, whatever) that could be merged or referenced. Let us not get into a struggle about correct or wrong tools. I really like the original idea of creating a commuity driven openSUSE book. We are already looking into ways how to interconnect wiki and/or openoffice with docbook. Ideas welcome! 1.1 Getting in touch with the SUSE Documentation Team ----------------------------------------------------- Reaching out to us is pretty easy - either subscribe to the opensuse-doc mailinglist (http://en.opensuse.org/Mailing_lists#Subscribing) or join the #opensuse-doc IRC channel on freenode. If you have typos, questions, suggestions or simply want to say hello, these are the places to go. You can also meet us in person at the openSUSE conference in Nuremberg this week. There will be a talk about one of our latest doc projects, the openSUSE Book Builder (see 2.3 below or refer to http://conference.opensuse.org/indico//contributionDisplay.py?contribId=71&…) We would be glad to see you there! 1.2 Reporting Documentation Bugs or Suggesting Adjustments ---------------------------------------------------------- Currently, two feedback channels are available if you have corrections or enhancements for us: - File a bug report (or an enhancement request) against the Documentation component for the respective product. Or, much easier: - Use the doc comment system: Go to http://www.novell.com/documentation/opensuse113/ where the openSUSE 11.3 documentation is hosted. Click on a manual title and navigate to the page where you have spotted an error/would like to suggest adjustments. Scroll to the bottom of that page and click on "Add comment". Insert your comment. If you are interested in getting feedback, provide your name and email address. Your comment is directly routed to our team, so we can take care of it. 1.3 Translating Manuals ----------------------- If you are interested in translating our manuals, we can provide the necessary infrastructure for you. Currently the Russian translation team already uses our SVN repository on berliOS to translate the openSUSE 11.3 manuals. 1.4 Contributing new Chapters or Books -------------------------------------- If you would like to contribute larger amounts of contents (chapters, sections, etc.), please get in touch with us (see above), and let us know what you like to contribute. Don't worry, you _DON'T_ have to know XML, susedoc, or the likes - that is something we can take care of ;-). 1.5 Contributing to the Build Environment (susedoc) --------------------------------------------------- susedoc is publicly hosted at https://developer.berlios.de/projects/opensuse-docmaker/ and can be checked out anonymously. Patches are welcome! If you are interested in contributing more than an occasional patch, you can get full access to the project. ###################################### # 2. Outlook: What's in the Pipeline # ###################################### The SUSE documentation has a few more projects in the pipeline. First and foremost we are working on making it easier for you to contribute. Second we have have planned two major software projects. 2.1 Publishing the Book Sources ------------------------------- The XML sources for our manuals are hosted on a Novell internal SVN server. We are currently in the process of moving them to a public SVN at berliOS, where they will be available for anonymous checkout. Document maintainers will get write access. As a first step, the SUSE Studio documentation and the openSUSE Documentation Style Guide are hosted at https://developer.berlios.de/projects/opensuse-doc/ More is to come very soon. We can also provide an infrastructure for manual translations on that server - in fact our Russian translators already make use of it. 2.2 Re-writing the Build Environment ------------------------------------ Our build environment (susedoc) currently is a mixture of tools using make, bash, python and perl. Although this tool collections works very well, we would like to consolidate it in order to make future enhancements easier. We have started to write a central docmaker library in perl and python which should provide everything that is needed to manage, monitor and build books from XML sources. Development of this library is in a very early state - if you are interested in helping us to develop it, get in contact with us. The sources are available from http://svn.berlios.de/wsvn/opensuse-docmaker/trunk/lib/ 2.3 openSUSE BookBuilder ------------------------ In short, the openSUSE BookBuilder is a library utilizing susedoc to automatically build books from XML sources. Added is a web application that serves as a virtual library. See http://conference.opensuse.org/indico//contributionDisplay.py?contribId=71&… for a more detailed description. If you are interested in that project, come to the talk at the openSUSE conference or contact me directly. ############################### # 3. List of openSUSE Manuals # ############################### openSUSE comes with with a lot of manuals in HTML and PDF format with a current page count of almost 2000 pages. Not all of them are shipped in the box. The HTML version of all manuals can be installed with the package opensuse-manuals_en. http://en.opensuse.org/openSUSE:Documentation_team#List_of_Manuals http://en.opensuse.org/SDB:Official_documentation ePUB versions can be downloaded from http://community.opensuse.org/ebooks/ebooks113/ 3.1 Startup Guide ----------------- Guides you through the installation and basic configuration of your system. For newcomers, the manual also introduces basic Linux concepts such as the file system, the user concept and access permissions and gives an overview of the features openSUSE offers to support mobile computing. Provides help and advice in troubleshooting. The Startup Guide is ca. 200 pages and is found in the openSUSE box. 3.2 Reference Guide ------------------- Gives you a general understanding of openSUSE and covers advanced system administration tasks. It is intended mainly for system administrators and home users with basic system administration knowledge. It provides detailed information about advanced deployment scenarios, administration of your system, the interaction of key system components and the set-up of various network and file services openSUSE offers. 3.3 GNOME User Guide -------------------- Introduces the GNOME desktop of openSUSE. It guides you through using and configuring the desktop and helps you perform key tasks. It is intended mainly for end users who want to make efficient use of GNOME desktop as their default desktop. 3.4 GNOME Quick Start --------------------- Gives a short introduction to the GNOME desktop and some key applications running on it. 3.5 KDE User Guide ------------------ Introduces the KDE desktop of openSUSE. It guides you through using and configuring the desktop and helps you perform key tasks. It is intended mainly for users who want to make efficient use of KDE as their default desktop. 3.6 KDE Quick Start ------------------- Gives a short introduction to the KDE desktop and some key applications running on it. 3.7 Application Guide --------------------- Learn how to use and configure key desktop applications on openSUSE. This guide introduces browsers and e-mail clients as well as office applications and collaboration tools. It also covers graphics and multimedia applications. 3.8 Security Guide ------------------ Introduces basic concepts of system security, covering both local and network security aspects. Shows how to make use of the product inherent security software like AppArmor (which lets you specify per program which files the program may read, write, and execute) or the auditing system that reliably collects information about any security-relevant events. 3.9 Installation Quick Start ---------------------------- Lists the system requirements and guides you step-by-step through the installation of openSUSE from DVD. 3.10 AppArmor QUick Start ------------------------- Helps you understand the main concepts behind AppArmor. Thanks to Frank, Tanja, Tom for compiling this writeup, (shame on me for messing it up). cheers, JW- -- o \ Juergen Weigert paint it green! __/ _=======.=======_ <V> | jw(a)suse.de back to ascii! __/ _---|____________\/ \ | 0911 74053-508 __/ (____/ /\ (/) | _____________________________/ _/ \_ vim:set sw=2 wm=8 SUSE LINUX Products GmbH, GF: Markus Rex, HRB 16746 (AG Nuernberg) "You are trying to use packages from project 'openSUSE:11.3'. Note that malicious packages can compromise your system." -- To unsubscribe, e-mail: opensuse-doc+unsubscribe(a)opensuse.org For additional commands, e-mail: opensuse-doc+help(a)opensuse.org

2 1

[opensuse-doc] FW: [opensuse-marketing] The openSUSE Handbook proposal
by Bryant, Christian 06 Oct '10

06 Oct '10

Think this should actually have been sent to this list :) - Christian Bryant -----Original Message----- From: Bryant, Christian [mailto:CABryant@mednet.ucla.edu] Sent: Wednesday, October 06, 2010 8:57 AM To: opensuse-marketing(a)opensuse.org Cc: 'Klaas Freitag' Subject: RE: [opensuse-marketing] The openSUSE Handbook proposal Just as a proof-of-concept for document writing community success, see http://flossmanuals.net - easy to use, produces nice output, has a great community of contributors. In terms of wiki-to-book, Wikipedia has had that for some time, and there are some nice examples out there: http://en.wikipedia.org/wiki/Help:Books I'm sure there is a way to build on that model for openSUSE. I have both the "good-writer-skill" and "I-like-to-fiddle-with-tools-which-produce-great-outcome", as Klaas puts it. But I also have to recognize which one of these others are as well, as a project manager or in a community leader roll. It's the users that should define what is pursued here, I believe. I think the wiki-to-book functionality should definitely be added to the openSUSE wiki as an option, and if it matured to a point where all the other features discussed in this thread could be produced, then all the better. For now, I am still using Emacs to edit my openSUSE documents - but the older I get, the simpler I like things to be :) I wouldn't turn away from a nice wiki that would squirt out a publish-ready document! Cheers, Christian Bryant >Couldn't we find people for these two groups instead: >- Editors: People who work on content and deliver in which format they ever > want (nearly ;-) to >- Book Builders: People who get the content from the Editors and work on > building a book with the best suited tool for that? >Maybe it makes more sense to devide the "good-writer-skill" from the "I-like- >to-fiddle-with-tools-which-produce-great-outcome" role? >regards, >Klaas IMPORTANT WARNING: This email (and any attachments) is only intended for the use of the person or entity to which it is addressed, and may contain information that is privileged and confidential. You, the recipient, are obligated to maintain it in a safe, secure and confidential manner. Unauthorized redisclosure or failure to maintain confidentiality may subject you to federal and state penalties. If you are not the intended recipient, please immediately notify us by return email, and delete this message from your computer. -- To unsubscribe, e-mail: opensuse-marketing+unsubscribe(a)opensuse.org For additional commands, e-mail: opensuse-marketing+help(a)opensuse.org IMPORTANT WARNING: This email (and any attachments) is only intended for the use of the person or entity to which it is addressed, and may contain information that is privileged and confidential. You, the recipient, are obligated to maintain it in a safe, secure and confidential manner. Unauthorized redisclosure or failure to maintain confidentiality may subject you to federal and state penalties. If you are not the intended recipient, please immediately notify us by return email, and delete this message from your computer. -- To unsubscribe, e-mail: opensuse-doc+unsubscribe(a)opensuse.org For additional commands, e-mail: opensuse-doc+help(a)opensuse.org

1 0

[opensuse-doc] Re: [opensuse-marketing] The openSUSE Handbook proposal
by Thomas Schraitle 06 Oct '10

06 Oct '10

Hi, (CC'ed opensuse-doc so doc people can read that too.) On Monday 04 October 2010 Christian Boltz wrote: > [...] > > I'm not sure about that. I don't say that it will be very easy, but it > should be possible, and it won't be too hard. You are underestimate the efforts. > 90% of the formatting can be done with plain wikitext, and for the > remaining 10% templates can be used (which can, but don't have to have a > visible effect in the wiki). A "visible" template might be something > like "text printed on screen", an "invisible" template might contain a > keyword for the book index. We use a feature in DocBook/Novdoc what is called "profiling". We label one paragraph for business related products and another one for openSUSE products. When we process the manual, the paragraphs are being "filtered" so only the requested product is visible in the end format. Maybe this belongs to the remaining 10%... > I think we could even develop a "XML skin" for mediawiki so that the > wiki can generate valid docbook/novdoc XML out of wiki pages (with > <para> instead of <p> etc.). > The alternative solution would be to post-process the wikitext or the > HTML to convert it to XML. Depending on the HTML this sounds scaring. > Basically the two methods don't differ too > much, the main difference/question is if you want XML output integrated > in the wiki or not. > > > I would propose XML hosted on SVN. Although the learning curve would > > be a bit stepper than with e.g. wiki markup it would give us the > > maximum flexibilty and a guaranteed future. > > I'm afraid that the learning curve is too high - lessons for lizards > unfortunately gave you/us that lesson... Sorry, but I never understood the "XML is too difficult" rant. People are *not* afraid to learn LaTeX or Wiki, dig into HTML, or even migrate from Windows to Linux because of "the learning curve is too high". Why they are not afraid? Because they are _interested_ and want to _learn_ something new. Why should it be difficult to learn DocBook/Novdoc? It's just a format as HTML, WikiText, ASCIIDoc, or anything else. Maybe it's a bit more verbose, but if you can write HTML and design your webpage, you can also write documentation in DocBook or Novdoc. It's just a matter of your XML editor. Of course, Lessons for Lizards was not as successful as we wished it would be. However, it's a bit too easy to blame only XML for the demise. Maybe it had an effect, maybe not. The biggest problem IMHO was time and marketing. > I don't know if the learning curve was the only problem there, but at > least it's "I have to learn another thing before I can contribute". I'm afraid, I have to disagree here. "To learn another thing before I can contribute" is the case for _every_ open source project. If you want to contribute, you usually use what's there. If you are interested enough then you are willing to take that "extra step". If not, you simply don't contribute. Just think of this example: People were not afraid to learn CVS. After some time, it was more or less replaced by Subversion. Although it was not that different, people were willing to learn the differences. Now it seems Git will be the sucessor for Subversion. And *that* is really different from CVS/Subversion! And what's the opinion? "Git is soo coool!" is what can I heare a lot. ;) > > Whatsmore, the existing documentation (speaking of almost > > 2000 pages!!) already uses XML. > > OK, _that_ is an argument. But as you already wrote, it shouldn't be > hard to convert it to wikitext. Indeed, there are stylesheets (I've wrote it), but I wouldn't want to transform a complete book. The two systems are too different in some aspects. > And it would be a good testbed for the > wikitext to XML converter - ideally there should be no difference after > converting it forth and back again ;-) (and that would make us better > than google translator *g*) > > [...] Let me suggest another idea: In my opinion, most people have problems with XML because it's (a) too verbose, (b) it's too "complicated", and (c) you don't see the result. At least that's what I hear a lot. As most of the functionality thesedays goes through the Web, why not have a XML editor in, let's say, Firefox? Of course, it should offer the usual features but would hide the XML syntax and display just the rendered text. I know, this is day-dreaming and the idea is not new. However, I think, this would lower the entrance. We could use the existing XML source without converting it to Wiki while embracing Web usability. I think, this should solve the above problems. Maybe we could use Bitflux, see http://bitfluxeditor.org/. > [...] > I see the public SVN as a fast solution so that people have a chance to > dig into the manual's source. It might even be read-only in the > beginning - having to upload patches to bugzilla or send them to the > -doc mailinglist is still easier than reporting "on page 123 in section > 'foo', there's a typo in 'baar'". A page number is a bad choice as it can change easily. Better use the section title or an anchor from HTML. :) > But even if you give out SVN write access, I'm afraid that not many > people will contribute to the XML source because of the learning curve. What makes you so sure? To cite Tim Berners-Lee: »If you use the original World Wide Web program, you never see a URL or have to deal with HTML. That was a surprise to me - that people were prepared to painstakingly write HTML.« > You have to "switch" from the rendered manual (HTML, PDF, ...) to the > XML source, and you have to know at least some XML basics. In Wikis you have to know some Wiki basics. What's the point here? :) > OTOH the wiki is more like a long(er)-term solution, but makes > contribution much easier - just click "Edit". Sorry, I'm not convienced. DocBook exists for more than 10 years! It's well- matured, very well documented, and it's one defacto standard for technical documentation. Ok, maybe you can count DITA as well. Although I'm not that much into the Wiki topic, I have the impression the Wiki syntax is not very well "established": One Wiki supports a certain syntax, another don't. If this is really the case, I wouldn't call Wikis "a long-term solution". For easier contribution: See my idea above. > Yes, writing a good wiki-to-XML tool will need some work, but it is > possible. And it is worth the effort IMHO. Why should we write some wiki-to-XML converter when we have already everything in place, ready to be used? > [...] > > You've seen the numbers from Rajko - around 90 active users in the last > 3 months. That's still 89 more than in the "lessons for lizards" *g,d&r* You compare apples with oranges. :) -- Gruß/Regards, Thomas Schraitle ---------------------------------------------------------------------- SUSE LINUX Products GmbH (o< Documentation Specialist Maxfeldstrasse 5 /\\ 90409 Nuernberg, Germany _\_v http://en.opensuse.org/Documentation_Team SUSE LINUX Products GmbH, GF: Markus Rex, HRB 16746 (AG Nürnberg) -- To unsubscribe, e-mail: opensuse-doc+unsubscribe(a)opensuse.org For additional commands, e-mail: opensuse-doc+help(a)opensuse.org

5 5

[opensuse-doc] NovDoc Usage
by Bryant, Christian 01 Oct '10

01 Oct '10

I'm going to be working on some custom appliances using SUSE Studio. I love the susedoc style sheets but I'm not clear on the usage requirements and wanted to make sure that I can use susedoc to create manuals for my appliances that look exactly like the actual openSUSE manuals. I know the code for susedoc is GPL but are there some documentation guidelines for folks like me that have this type of project in mind? Thank you. Cheers, Christian Bryant, UCLA Health System Project Manager, IT Operations Medical Information Technology Services (MITS) IMPORTANT WARNING: This email (and any attachments) is only intended for the use of the person or entity to which it is addressed, and may contain information that is privileged and confidential. You, the recipient, are obligated to maintain it in a safe, secure and confidential manner. Unauthorized redisclosure or failure to maintain confidentiality may subject you to federal and state penalties. If you are not the intended recipient, please immediately notify us by return email, and delete this message from your computer. -- To unsubscribe, e-mail: opensuse-doc+unsubscribe(a)opensuse.org For additional commands, e-mail: opensuse-doc+help(a)opensuse.org

3 3

[opensuse-doc] Re: [opensuse-marketing] The openSUSE Handbook proposal
by Frank Sundermeyer 30 Sep '10

30 Sep '10

On Thu, 30 Sep 2010 00:54:30 +0200 Jos Poortvliet wrote: Hi, > On Thursday 30 September 2010 00:26:09 Helen wrote: > > How hard is it to convert to multiple e-reader formats including > > PDF? > > That is actually a pretty good point. If our Wiki is good enough in > terms of content, we can try and figure out how to automate creating > a book. Well, fully automatic would probably be hard - a book would > need a bit of layouting. But having all the content on the wiki, then > using it for a complementary book - I think that's the way to go. I completely disagree. You are proposing to create documentation in a completely unstructured format and then writing parsers attempting to create an exchangeable format. It is re-inventing the wheel by starting with a rectangle. We already have all the style-sheets for XML to provide the formats we need (including wiki text). -- Regards Frank Frank Sundermeyer, Technical Writer, Documentation SUSE Linux Products GmbH, Maxfeldstr. 5, D-90409 Nuernberg Tel: +49-911-74053-0, Fax: +49-911-7417755; http://www.opensuse.org/ SUSE Linux Products GmbH, GF: Markus Rex, HRB 16746 (AG Nuernberg) "Reality is always controlled by the people who are most insane" Dogbert -- To unsubscribe, e-mail: opensuse-doc+unsubscribe(a)opensuse.org For additional commands, e-mail: opensuse-doc+help(a)opensuse.org

1 0

[opensuse-doc] Re: [opensuse-marketing] The openSUSE Handbook proposal
by Frank Sundermeyer 30 Sep '10

30 Sep '10

On Thu, 30 Sep 2010 14:01:14 +0200 Bryen Yunashko wrote: Hi, > I'd like to recommend that we also consider making this available on > ebooks such as Kindle or Nook. I recently got my Kindle and I'm > really enjoying the ability to quickly get my books and have it ready > at all times. in case you haven't done so, you might want to try the 11.3 eBooks http://community.opensuse.org/ebooks/ebooks113/ Feedback welcome. -- Regards Frank Frank Sundermeyer, Technical Writer, Documentation SUSE Linux Products GmbH, Maxfeldstr. 5, D-90409 Nuernberg Tel: +49-911-74053-0, Fax: +49-911-7417755; http://www.opensuse.org/ SUSE Linux Products GmbH, GF: Markus Rex, HRB 16746 (AG Nuernberg) "Reality is always controlled by the people who are most insane" Dogbert -- To unsubscribe, e-mail: opensuse-doc+unsubscribe(a)opensuse.org For additional commands, e-mail: opensuse-doc+help(a)opensuse.org

1 0

[opensuse-doc] Re: [opensuse-marketing] The openSUSE Handbook proposal
by Frank Sundermeyer 30 Sep '10

30 Sep '10

On Thu, 30 Sep 2010 07:57:52 +1000 Helen wrote: Hi, > I like the idea of a 'go to' book but understood that this was the > function of the wiki. Do I have the wrong impression? > > Duplicaton of effort is a bad idea, but I do like having the 'best and > most current' readily available. > > A related issue is navigation and SEO of existing material. For > instance, a search for 'install nvidia drivers opensuse' and this page > is first > > http://www.suse.de/~sndirsch/nvidia-installer-HOWTO.html#1 > > or by clicking through the portal I find this > > http://en.opensuse.org/SDB:NVIDIA_drivers (nice 'one click' for > newbies) > > which page do we want new users to land on? > > Having another book is no good if a user doesn't think to read it, or > doesn't find it when they google a question. good points. It's not only about not finding it, it's also about finding several different writings on one topic from one source (openSUSE). The same topic (NVIDIA) is also extensively covered on the forums with a HowTo. Whatsmore at least three different openSUSE people are maintaining documents about the same topic. What a waste of resources. So IMHO centralising is the way to go instead of forking. If every writing has a single source, it doesn't matter if there are several hits in Google, since they all will say the same. If every document has a single source, ppl can work _together_ on this document to make it the one HowTo for openSUSE that answers all questions. -- Regards Frank Frank Sundermeyer, Technical Writer, Documentation SUSE Linux Products GmbH, Maxfeldstr. 5, D-90409 Nuernberg Tel: +49-911-74053-0, Fax: +49-911-7417755; http://www.opensuse.org/ SUSE Linux Products GmbH, GF: Markus Rex, HRB 16746 (AG Nuernberg) "Reality is always controlled by the people who are most insane" Dogbert -- To unsubscribe, e-mail: opensuse-doc+unsubscribe(a)opensuse.org For additional commands, e-mail: opensuse-doc+help(a)opensuse.org

1 0

[opensuse-doc] Re: [opensuse-marketing] The openSUSE Handbook proposal
by Frank Sundermeyer 30 Sep '10

30 Sep '10

On Thu, 30 Sep 2010 13:40:44 +0200 Will Stephenson wrote: Hi, > On Thursday 30 September 2010 13:00:02 Frank Sundermeyer wrote: > > On Thu, 30 Sep 2010 00:56:25 +0200 Javier Llorente wrote: > > > > Hi, > > > > > On Miércoles, 29 de Septiembre de 2010 21:00:29 Raul Libório > > > escribió: > > > > Would be a complement to > > > > http://en.opensuse.org/SDB:Official_documentation? > > > > > > Yepp. Some topics aren't covered in the official docs. > > > Nevertheless, it could be reused. > > > > I would prefer to improve and extend the existing documentation > > rather than to fork it... > > Frank, I'm glad to see you on this thread. I doubt the current > activity on Piratepad comes from a desire to fork, but instead out of > ignorance how to contribute. please everyone interested in contributing to the existing openSUSE documentation or to Lessons for Lizards (cookbook) come to the opensuse-doc mailinglist to discuss details! > Perhaps you could find the links to how to contribute to the existing > documentation and explain how our in-house docu system allows > publishing in multiple formats? Elsewhere in the thread people > suggested making proper ebook reader formats. Well, up to now there hasn't been a need to open our documents to contribution, because simply no one has asked for it. But as I pointed out in another post, everything has already been set up on Berlios, so we can make our sources available in short time. As for the "how", it is basically (the instructions are 3 years old) the same that applied to the Lessons for Lizards project. http://developer.novell.com/wiki/index.php/Lessons_for_Lizards See the "Getting help" section for details. As a quick start, if ppl are interested, we could revive the LfL project on Berlios. Could be ready some time next week. Lately we have been working on an automatic Book Building software with a virtual web based library called openSUSE Book Builder. That would come in handy when having a community book project ;-). Everyone interested please come to our talk at the conference: http://conference.opensuse.org/indico//contributionDisplay.py?contribId=71&… -- Regards Frank Frank Sundermeyer, Technical Writer, Documentation SUSE Linux Products GmbH, Maxfeldstr. 5, D-90409 Nuernberg Tel: +49-911-74053-0, Fax: +49-911-7417755; http://www.opensuse.org/ SUSE Linux Products GmbH, GF: Markus Rex, HRB 16746 (AG Nuernberg) "Reality is always controlled by the people who are most insane" Dogbert -- To unsubscribe, e-mail: opensuse-doc+unsubscribe(a)opensuse.org For additional commands, e-mail: opensuse-doc+help(a)opensuse.org

1 0

[opensuse-doc] Re: [opensuse-marketing] The openSUSE Handbook proposal
by Frank Sundermeyer 30 Sep '10

30 Sep '10

oops, address typo in the initial mail On Wed, 29 Sep 2010 21:59:56 +0200 Jos Poortvliet wrote: Hi, > On Wednesday 29 September 2010 20:27:11 Javier Llorente wrote: > > Hello there, > > > > I was thinking that having an openSUSE Handbook (or handbuch ;) in > > pdf format ready to be downloaded, printed and even ready to be > > sent to a publishing company is a good idea. > Ambitious, but a good idea. We can do the writing either on the wiki > or in piratepads (but piratepad has been acting up lately, I really > really hope someone feels like setting up an Etherpad for openSUSE). I am not convinced. * Javier's idea was to produce documentation in different output formats - at least HTML and PDF. I would like to add ePUB and ASCII. * It was pointed out that there different projects producing and/or reusing openSUSE documentation * There is a need to be able to share the documentation All this does not sound like a wiki or *pad is the tool of choice. Once you choose to use these tools it is pretty hard or even impossible to switch to another tool, to add another output format, to reuse existing files in different documents (having a single source to maintain). I would propose XML hosted on SVN. Although the learning curve would be a bit stepper than with e.g. wiki markup it would give us the maximum flexibilty and a guaranteed future. Whatsmore, the existing documentation (speaking of almost 2000 pages!!) already uses XML. Apart from that, even if XML would be no choice at all, why using another tool apart from our wiki? What's wrong with en.opensuse.org (apart from the search ;-)) ? Plans to host the complete openSUSE documentation in a public SVN at berlios exist for quite some time, the structure is already in place, everything is prepared... . > ... and get ppl to write... That will be the hardest part. How many _regular contributors_ (not speaking of ppl doing administrative tasks) do we have in the wiki? -- Regards Frank Frank Sundermeyer, Technical Writer, Documentation SUSE Linux Products GmbH, Maxfeldstr. 5, D-90409 Nuernberg Tel: +49-911-74053-0, Fax: +49-911-7417755; http://www.opensuse.org/ SUSE Linux Products GmbH, GF: Markus Rex, HRB 16746 (AG Nuernberg) "Reality is always controlled by the people who are most insane" Dogbert -- To unsubscribe, e-mail: opensuse-doc+unsubscribe(a)opensuse.org For additional commands, e-mail: opensuse-doc+help(a)opensuse.org

1 0

[opensuse-doc] Re: [opensuse-marketing] The openSUSE Handbook proposal
by Frank Sundermeyer 30 Sep '10

30 Sep '10

On Thu, 30 Sep 2010 00:56:25 +0200 Javier Llorente wrote: Hi, > On Miércoles, 29 de Septiembre de 2010 21:00:29 Raul Libório escribió: > > Would be a complement to > > http://en.opensuse.org/SDB:Official_documentation? > > Yepp. Some topics aren't covered in the official docs. Nevertheless, > it could be reused. I would prefer to improve and extend the existing documentation rather than to fork it... -- Regards Frank Frank Sundermeyer, Technical Writer, Documentation SUSE Linux Products GmbH, Maxfeldstr. 5, D-90409 Nuernberg Tel: +49-911-74053-0, Fax: +49-911-7417755; http://www.opensuse.org/ SUSE Linux Products GmbH, GF: Markus Rex, HRB 16746 (AG Nuernberg) "Reality is always controlled by the people who are most insane" Dogbert -- To unsubscribe, e-mail: opensuse-doc+unsubscribe(a)opensuse.org For additional commands, e-mail: opensuse-doc+help(a)opensuse.org

1 0

[opensuse-doc] Re: [opensuse-marketing] The openSUSE Handbook proposal
by Frank Sundermeyer 30 Sep '10

30 Sep '10

On Wed, 29 Sep 2010 20:27:11 +0200 Javier Llorente wrote: Hi, (Disclaimer: I am working in the SUSE documentation department and am the person leading the openSUSE documentation project in our department) I am not reading opensuse-marketing (doing that now ;-)), but henne pointed me to this thread, therefore I did not answer earlier... Please move this discussion to opensuse-doc, where you can reach all people currently writing the openSUSE manuals as well as other people interested in documentation > I was thinking that having an openSUSE Handbook (or handbuch ;) well, this may come as a surprise to most of you, but we already have that - and it's even shipped with each openSUSE version. The problem is that it is kind of a stealth documentation because it is almost impossible to find it when you do not know where to find it. The fact that most of you having participated in this thread are not aware of the existing documentation is proof for that. The documentation team has fought for a better visibility of the documentation for years with to avail - it would be good if you would join us and help us in this matter. Installing them by default (HTML and PDF) would be a good start. Having a documentation pattern would be a nice addition. Having a desktop icon providing access to the manuals as well as a menu entry in the main menu would make people aware of the documentation. Putting some work into the KDE and GNOME help centres to make them do what they are supposed to do would be another milestone ;-). Here is where you can find the official openSUSE documentation: Web: http://en.opensuse.org/SDB:Official_documentation System: Packages: HTML: * opensuse-manuals_en PDF: * opensuse-apparmor-quick_en-pdf (openSUSE AppArmor Quick Start) * opensuse-apps_en-pdf (openSUSE Application Guide) * opensuse-gnomequick_en-pdf (openSUSE GNOME Quickstart * opensuse-gnomeuser_en-pdf (openSUSE GNOME User Guide * opensuse-installquick_en-pdf (openSUSE Installation Quick Start) * opensuse-kdequick_en-pdf (openSUSE KDE Quickstart) * opensuse-kdeuser_en-pdf (openSUSE KDE User Guide) * opensuse-reference_en-pdf (openSUSE Reference) * opensuse-security_en-pdf (openSUSE Security Guide) OK, having had my rant here is my answer to Javier's initial mail and to other comments/proposals: See > in > pdf format ready to be downloaded, printed and even ready to be sent > to a publishing company is a good idea. We currently provide color PDFs, HTML, and ePUB. We can also provide a ready-to-print PDF, neatly formatted ASCII, and MediaWiki text (basic functionality, stylesheets could need some work). The openSUSE documentation is created in XML (a subset of DocBook), because this is the only format that gives us the flexibility to produce almost every output format we currently need or will need in the future (we only recently dded ePUB). All openSUSE manuals are licensed under the GFDL. > ****************************** > The openSUSE Handbook > ****************************** > Introduction > - What's the openSUSE project? > - What's openSUSE? Currently not covered in our manuals, but since the text is already available in the wiki, adding it should be fairly easy. > Installing openSUSE > - Different types of install methods Covered to some extend in the reference guide, if there is need this could be extended. The default installation path is also described as a step-by-step guide with screenshots in the Installation Quick Start. > - AutoYaST Currently not part of the openSUSE manuals, but documentation exists for SLE and could be added. So far this hasn't been asked for. > Installing applications > - Using 1-click > - Using YaST > - Using zypper All covered in the reference and Start-Up Guides > Desktop environments > - An introduction to DEs (KDE, GNOME, XFCE, LXDE). * Gnome Quick Start * Gnome Manual * KDE Quick Start * KDE Manual * Application Guide XFCE and LXDE currently not available, this would need help from the community. In case of XFCE I would vote against writing our own manuals because the documentation provided by XFCE itself is very good. Maybe a quickstart (I probably could do it myself since I am an XFCE user). I do not know what's the status of the LXDE documentation, though. > - Enabling proprietary drivers (ATI, NVIDIA) this seems to change with every release and always implies last minute changes - this is definitely a topic for the wiki, since a manual would probably already be outdated on release date > - Multimedia Covered in the KDE, Gnome and Application Guides > - Printing Covered in the Start-Up and (all the gory details) the Reference Guide > - Games Currently not covered. To be honest, I do not see the need to document them (it would probably just be copying the existing documentation) > System administration > - Introduction to the command line > - Networking > - Security > - Storage > - Virtualization > - Keeping openSUSE up-to-date > - Upgrading openSUSE Everything is covered except Virtualization and Storage. Both topics are covered in SLES, so documentation is available in principle. So far, Product Management hasn't seen a need to include them with openSUSE. > Servers > - Apache and lighttpd Apache is covered in detail, lightttpd not. IMHO it is sufficient to document one of the two. > - MySQL and PostgreSQL > - Postfix > - BIND > - Samba All not covered. The reason for this is: Very good books each with several hundred pages exist on the market. We will not be able to cover those topics to the same extend as the books do. What we could do is to provide a basic introduction and that would not fit these complex topics. > - CUPS Covered in the Reference Guide > etc We also have a security Guide. > > Other openSUSE Technologies > - Build Service > - KIWI Both projects are under heavy development and are constantly changing. Documentation has to be written and maintained by the projects themselves, otherwise you will just produce outdated manuals that will help nobody. ;-) > - SUSE Studio We have just finished writing a Studio guide (released under GFDL). It will be published under www.novell.com/documentation any day soon. > Drawbacks: > We would need to update some of its contents for each openSUSE > release. It needs more than two people to make it happen ;-) It's more than that. the complete manual needs to be _reviewed_ and some of it's content has to be updated. The updated parts need to be proofread (content-wise and language-wise). The biggest challenge is, that all this has to be finished two weeks before release date. otherwise the manuals will not make it into the distribution. If the manuals are going to be translated (currently some guides are translated into German), they have to be ready 5 weeks before release date... . > On the other hand, I think that the handbook would make openSUSE more > "visible" and a bit more "ready to use." > > Comments and suggestions are welcome! :-) Use what is already there and help to improve it ;-). Three years ago we (the Nuremberg documentation team) launched a project called Lessons for Lizards. The idea was to have a cookbook style manual covering all sorts of topics that don't make the official manuals. We provided the complete infrastructure (SVN, mailinglist, build environment, support, etc.) and a skeleton book that already included a few articles and a structure. The project was announced on different channels including a speech of mine at FOSDEM. We had a _single_ contributor (thanks a lot Alexey!) from the community and so the project slowly died... . (although it could be revived very quickly). -- Regards Frank Frank Sundermeyer, Technical Writer, Documentation SUSE Linux Products GmbH, Maxfeldstr. 5, D-90409 Nuernberg Tel: +49-911-74053-0, Fax: +49-911-7417755; http://www.opensuse.org/ SUSE Linux Products GmbH, GF: Markus Rex, HRB 16746 (AG Nuernberg) "Reality is always controlled by the people who are most insane" Dogbert -- To unsubscribe, e-mail: opensuse-doc+unsubscribe(a)opensuse.org For additional commands, e-mail: opensuse-doc+help(a)opensuse.org

1 0

[opensuse-doc] Official docs openSUSE 11.3
by Tim Mohlmann 20 Jul '10

20 Jul '10

Hello Doc list, For the wiki, I would like to know when will the official novell docs be published? As for every version we create a link from the wiki to this original docs. At this moment I can't find anything on http://www.novell.com/documentation. Greetings, Tim Mohlmann (wiki team) -- To unsubscribe, e-mail: opensuse-doc+unsubscribe(a)opensuse.org For additional commands, e-mail: opensuse-doc+help(a)opensuse.org

2 1

[opensuse-doc] Acess to opensuse-doc on berlios
by Luiz Fernando Ranghetti 25 May '10

25 May '10

Hi, Could I have acess (read only is sufficient - elchevive is my username) to opensuse-docs in berlios.de? As annonymous I can't see the books\distribution\en contents (only a locdrop folder) Regards, Luiz -- To unsubscribe, e-mail: opensuse-doc+unsubscribe(a)opensuse.org For additional commands, e-mail: opensuse-doc+help(a)opensuse.org

2 1

[opensuse-doc] license texts update
by Juergen Weigert 22 Apr '10

22 Apr '10

Hi! I've walked throught he various license related files common_copyright_quick.xml common_copyright_opensuse.xml common_copyright_sle.xml common_legal.xml common_gplv2_i.xml common_gfdl_i.xml in our internal and external repositories and edited them to look more appealing. At least more appealing to me. I am half lawyer half developer, so your milage may vary. * The full texts of GFDL and GPL now appear exactly as written by the FSF. There were some minor edits, that we are not entitled to do. * The copyright line of the GFDL boiler plate now says "(C) 2006-2010 Novell Inc. and contributors. All rights reserved." instead of several other forms, none of which honored any non-Novell contributors. (The term 'All rights reserved' is a nice-to-have for layers, but has no factual effect -- it bows to the terms of the GFDL.) * Call the licenses GPLv2, GFDLv2.1 instead just GPL and GFDL. Dinar, I also touched some files under */ru/, where I understood the english. Please let me know if I messed up something. Hope not :-) cheers, JW- -- o \ Juergen Weigert paint it green! __/ _=======.=======_ <V> | jw(a)suse.de back to ascii! __/ _---|____________\/ \ | 0911 74053-508 __/ (____/ /\ (/) | _____________________________/ _/ \_ vim:set sw=2 wm=8 SUSE LINUX Products GmbH, GF: Markus Rex, HRB 16746 (AG Nuernberg) -- To unsubscribe, e-mail: opensuse-doc+unsubscribe(a)opensuse.org For additional commands, e-mail: opensuse-doc+help(a)opensuse.org

2 1

[opensuse-doc] request for ru branch for susebook on berlios
by Dinar Valeev 21 Apr '10

21 Apr '10

Hello, I'm interested in to start translation of susebook to Russian language for 11.3 and Factory. Could you please create new branch on berlios.de and give me access rights? My berlios login name is k0da Thanks in advance, Dinar Valeev -- To unsubscribe, e-mail: opensuse-doc+unsubscribe(a)opensuse.org For additional commands, e-mail: opensuse-doc+help(a)opensuse.org

5 9

[opensuse-doc] Opensuse KDE Documentation
by Burkhard Lück 08 Apr '10

08 Apr '10

Hallo Doku-Wichtl, I am working since some years in the german translation team and in the kde documentation team. A few days ago I accidently found this page http://www.novell.com/documentation/opensuse112/ with a KDE User Guide and a KDE Quickstart Manual for KDE 4. I am writing here for several reasons: * using modified parts of these documentation in KDE. The documentation is Copyright 200-2009 Novell Inc. and FDL licensed? I found source rpm's on download.opensuse.org, is there any other way to get read-only access to the latest version of these docs in a repository? * collaboration on updating/extending this documentation. It's strange that two groups work on documentation for KDE whithout even knowing each other and waste their limited time with duplicated work. TIA for your feedback. -- Burkhard Lück KDE Documentation Team kde-doc-english(a)kde.org KDE Translators kde-i18n-doc(a)kde.org -- To unsubscribe, e-mail: opensuse-doc+unsubscribe(a)opensuse.org For additional commands, e-mail: opensuse-doc+help(a)opensuse.org

2 4

[opensuse-doc] Power Outage
by ml-admin＠opensuse.org 11 Sep '09

11 Sep '09

Broadcast message from ml-admin(a)opensuse.org (/dev/pts/0) at 07:30 GMT ... The system is going down for halt NOW! -- To unsubscribe, e-mail: opensuse-doc+unsubscribe(a)opensuse.org For additional commands, e-mail: opensuse-doc+help(a)opensuse.org

1 0

[opensuse-doc] XSLT question - how to hide some items?
by Christian Boltz 09 Dec '08

09 Dec '08

Hello, sorry for abusing this list for XSLT questions, but well, some people here (hello Thomas!) are too good in this area ;-) I have two small issues with my patch2mail (update notification) script: It includes two lines at the end of the output which I'd like to supress: <?xml version="1.0"?> Daten des Repositorys laden...Installierte Pakete lesen... The first one is obviously the XML "header", the second one is composed from two <message type="info">...</message> lines. The current XSLT file is attached - you can feed it with zypper --xmlout -t patch | xsltproc patch2mail.xsl - if you want to test it. What do I have to change to remove the above lines? (Note: Only messages with type "info" should be hidden.) Regards, Christian Boltz -- Werbung lügt, Corporate Design sagt die Wahrheit. Naja, alle _guten_ Komponenten der Wahrheit. :-) [Ratti]

3 8