September 2010 - openSUSE Documentation

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