Momonga Project Kondara Project A guide how to write &moshort; documents. 0.4 Mon Mar 5 2004 &muradaikan; - English translation upto Japanese version 1.11 0.3 Sun Aug 3 2003 &muradaikan; - English translation upto Japanese version 1.10 0.2 Mon Jul 8 2002 tamo - www/docs -> docs - trivials (see cvs diff. hehehe) - sorry i didnt see ja-version 0.1 Fri May 8 2002 &muradaikan; - English translation from Japanese version 0.6. &moproject; employs subversion to maintain our web site contents. In doing so, it allows us to create the most up to date contents at hand and put it on &moproject; web sever. To commit to &moproject; web site contents svn repository, you need to have an account at &moproject;. So if you would like to contribute to &moproject; web site publishing, please read Participating in Momonga Projectapply for your account. The contents of &moproject; web site under http://www.momonga-linux.org/docs/ can be retrieved by command anonymous svn. &moproject; Document License is defined as below. License The distribution license for all the documents created at the &moproject; is subject to the Open Publication License (OPL), excluding License Option A and B. For details on the OPL, refer to http://www.opencontent.org/openpub/. Japanese version of the OPL draft version 1.0 by Mr. Masayuki Hatta is available at http://www.opensource.jp/openpub/. Author The author of the documents created at the &moproject; should be &moproject; and the names of the writers for the first version and revisions shall be stated in the revision history. It is the case that an original document exists and the license is defined by the original. In such case the priority is given to the original license. (Example: translation, etc.) However, the original license may prohibit the &moproject; to manage or revise the original document. In such case the &moproject; will not handle the document. For dealing with such document, if we ever come across one, we will draw a conclusion after discussing in the Members Mailing List. In order to notate the license on the documents, such as manuals and HOWTOs, in www/docs, we add a section, exemption from responsibility and copyright, and stipulate the license there. For a concrete document contents, please refer to in this document. This example is the case for the OPL. Add a line to the file as follows: Copyright (c) 2002 Momonga Project. All Rights Reserved. For HTML files, a template is available and recommended to use. First, let's start from applying for an account to write documents at &moproject;. Please refer to project.html.en. Once you get your account, checkout the contents available from &mosaba;. You will be asked for your passphrase, so enter your passphrase and press Enter key. Then your checkout starts. $ svn co svn+ssh://your_account@svn.momonga-linux.org/home/snvroot/svnroot_docs/trunk/docs Enter passphrase for key '/home/hoge/.ssh/id_rsa': $ svn co svn+ssh://your_account@svn.momonga-linux.org/home/svnroot/svnroot_www/trunk/www Enter passphrase for key '/home/hoge/.ssh/id_rsa': Or, you can use anonymous svn to checkout the docs contents. $ svn co svn://anonsvn.momonga-linux.org/svnroot_docs/trunk Using anonymous svn wouldn't let you commit your editing result. Please apply for your own account if you want to commit. Doing either of the above operation will create directories, docs and www, under the current directory. Let's call these directories "docs" and "www" directories from here onwards in this document. The following lists packages required to edit &mosaba; contents: libxml2-devel libxslt docbook-style-xsl docbook-dtds xml-common scrollkeeper Required for documents under www directory. Required for documents under docs directory. Confirmed to work with libxslt-1.0.5-2k or later version. Required for documents under docs directory. Must be docbook-style-xsl-1.45-4k or later version. Necessary for documents under docs directory. Necessary for documents under docs directory. &molong; 1.0 or later contains all of these packages ready for use. Use Makefile in both docs and www directory. In www directory do $ make to create Automatic creation of Documents related to Announcement. A Makefile is not there if you svn checkout docs directory for the first time. In docs directory, run a script autogen.sh to create a Makefile. $ ./autogen.sh After that, do make. When a new document is added, in order to add the new document entry, run autogen.sh and then make. Directory contents under docs are written in a format called "DocBook" and files like html file that you can see with a browser are converted from DocBook to html. About DocBook format we will explain further in , so here we explain other contents that are not covered there. Documents related to &mosaba; announcement are the files that are to be updated every time &moproject; makes a new announcement. Currently such files are : announcement.html.en announcement.html.ja index.html.ja index.html.en momonga.rdf These documents can be mechanically created once a particular announcement content is modified. For example, something like "&molong; 1.0 RC1 is released. Please wait just for a little while until they are mirrored to our ftp mirror servers.". To do so, edit a file announcement.lang to have an announcement content. From there, related files will be created. Also, parts in each html files that are not directly related to the announcement, For example, a list of "Contents" in index.html.en. are contained in filename.in. To change layout of a document or add a new contents, please edit .in file. Here is an explanation of format in announcement.lang, which serves as a source of automatic creation of html files. Please note that ONLY Japanese filenames, announcement.ja is not used but announcement.eucjp is used. This file is written in xml format. Basically, the part that would need changing is between <item> and </item>, so we explain only this part here. One item element is for one announcement, so a task adding a new announcement is equal to adding a new item element. Following is a list of tags that you can use within item element. account To identify the author of the announcement. Write in your account name at &moproject;. key Key information to identify the announcement. Write a character line which has only one meaning in the announcement. date Date of announcement. title Contents of the announcement. link URL linked from the announcement. It can be omitted and if so, no link will be made. For example, here is an entry in an announcement. <item> <account>dora</account> <key>momo1.0rc1</key> <date>2002/07/15</date> <title>&molong; 1.0 RC1 was released. Please wait just for a little while until they are mirrored to our ftp mirror servers.</title> <link>announcement/1_0_rc1.html.en</link> </item> When a new announcement is added, execute make and confirm the desired result is synthesized before you do svn commit. Files other than announcement related documents under docs are written in ordinary manner. Whether it is html or text, or even if it is pdf or flush, such file should have been created in an appropriate manner to its specification, so edit it like any other file of the type and do svn commit. To add a new html file, it is handy to create one by editing the necessary portion of template.html.{ja,en}. DocBook format documents are stored in directory docs in svn directory. For example, this document is written as docs/Document-HOWTO/C/Kondara-Doucment-HOWTO.xml, a DocBook file. To modify this document, go todocs/Document-HOWTO/C directory, and edit Doucment-HOWTO.xml. Documents under this directory is basically xml files written in accordance with XML Document Type Definition (DTD). Documents that can be seen on the web site, including this one, are html files created by xsl conversion from xml source files. Details about DocBook itself can be found at: Practical DocBook Guide for Beginners (in Japanese), and LDP Author Guide are available from Linux JF Project This document is stored in here but if you try to see it with a browser, things may not look right. To change it in to something like this you need to use style sheet. There are dsssl and xslt style sheet that DocBook can use but &moproject; has chosen xslt for its simplicity in maintaing the style sheet. There are style sheet, dsssl and xslt, that you can use with DocBook. The &moproject; employed xslt for its simplicity for maintenace. If an environment that can do xslt conversion is at hand, you can check how it would appear once it is put on &mosaba;. Also errors in creating html files can be avoided by performing a conversion at hand after all the editing is complete. Style sheet that are actually used at &mosaba; are also maintained by svn and committed as docs/docbook.xsl docs/onehtml.xsl These style sheets are "Drivers" and style sheet itself is included in a package, docbook-style-xsl-version-releasem.noarch.rpm. Here you can take "drivers" as something that call and give certain parameter(s) to the style sheet. Referring to , create a Makefile. After doing so, in docs run make command. It will take a while to create all html files converted from xml files. If you want to ckeck result of, say, only one .xml file, do make in the directory where the .xml file exist. When it is complete, under each document directory there will be index.html structured html files for each section that are linked from the index.html changelog.html directory name_all.html directory name.txt There are a few manners and rules that should be followed in writing &molong; documents as mentioned below. Considering the amount of documents placed on &molong;, we assume "article" to be used for root element of a document. docbook-style-xsl style sheet package is DocBook's a generic style sheet so it should be ok to use Perhaps "books"? but we haven't tried it on anything other than article. Also the process to create changelog.html with docbook.xsl driver is relying on article. Somebody please write up a cool code for this. Among the style sheets used for &molong; documents,docbook.xsl is set to produce individual html files for each <sect1>. In this case, a file name is created with an id character name of each <sect1>. For example, a section with the following <sect1 id="kakikata"> will be created as kakikata.html. If a section has no id character is specified, ar01s??.html wil be created. It stands for article 1 section ??. With this manner, the file name would change depending on the order of the section in the article. If this section needs to be linked from other web site, add id character to have a fixed file name for the link. However, avoid using "changelog" for id character since a style sheet in docbook.xsl is set to create changelog.html from the contents of <revhistory> section. The same goes for anchors to <sect2>. If it needs to be linked from other web site, put some unique id character. &molong; documents use entry definition for frequently appearing words and expressions in the document. In the actual documents, the references from the definition is written. This may sound a bit hard to understand but in short, it means to define something like &lt;, often seen in html, and use it. For example, we write definitions of frequently appearing expressions in the &molong; documents. or something similar. The reasons behind doing this way are: Prevention of typographical errors Definitions for "&molong; -> &molong;" can avoid an error too common among the "Momomga Linux". Also if there is a mistake like &morong; which is not defined, xml parser may let you know that there is an error. Easy to change definition reference An entry definition like "&svnsaba; -> &svnsaba;" can easily modified to update when your svn server for web contents is moved. Easy to make Using a definition like "&dora; -> &dora;" can save you a lot of typing. It can also contribute to less typograhical errors. And things like rpm changelog go wild ... It amazes me that sometimes you can't even type your own name right ... The entry definition file for &molong; document is docs/momonga.ent. <!ENTITY molong "Momonga Linux"> <!ENTITY moshort "Momonga"> Definitions are made in this way so you can add up when necessary. Currently under discussion. Finalized decision will be written here. :) If there is a syntax error in your document, updating the actual contents of &mosaba; may be stopped, or &omokon; may be halted from the error when your document is being created in &moshort;-Docs package(as planned). To avoid such a situation, perform as below to check locally before you commit to svn. $ xmllint --noout --valid Hoge-HOWTO.xml Let's use Hoge-HOWTO as our sample here. Create a directory in the same name as the document under docs. Then do $ svn add new directory to put it under the control of svn. Then do svn commit as required. In the directory you prepared at , create an xml file in the same name as the directory name. I know that there is a subtle discrepancy between and but hope readers can pick up what we mean ... Perhaps in creating this xml file mere copying one from another document directory might be a quick fix but let me write some rules to apply at the beginning of the file. <?xml version="1.0" encoding="EUC-JP"?> <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ <!ENTITY % kent SYSTEM "../../momonga.ent"> %kent; ]> <article id="index" lang="ja"> A declaration that this file is an xml file. Xml has UTF-8 as default encoding. When another encoding is used, it should be declared as well. A declaration to use XML DocBook DTD Version 4.1.2. URL where DTD is actually located. This is mandatory since it is not DocBook sgml. Reading in momonga.ent file. Take this as a declaration to use references defined in momonga.ent file. This is an root element of this document,article. From its id character the output file would be index.html. Since it is in Japanese, lang character is set as ja. As a result of this, output html files would have ja as language type, would be encoded in EUC-JP, and have "Table of Contents" translated to the appropriate term in the language. Omf stands for Open Source Metadate Framework. For details, refer to metalab. Create as docs/Hoge-HOWTO/C/Hoge-HOWTO-C.omf. Its contents should be <?xml version="1.0" encoding="ISO-8859-1" standalone="no"?> <omf> <resource> <title> Hoge-HOWTO </title> <subject> <category>General|Linux|Distributions|Momonga</category> </subject> <format mime="text/xml"/> <identifier url="Hoge-HOWTO.xml"/> <language code="C"/> </resource> </omf> Something like that. In docs/Hoge-HOWTO/Makefile.am, list up directories specific to available languages like below: SUBDIRS = C ja In docs/Hoge-HOWTO/C/Makefile.am, it should have something like the following: docname = Hoge-HOWTO lang = en omffile = Hoge-HOWTO-C.omf xml_ents = include $(top_srcdir)/xmldocs.make dist-hook: app-dist-hook figs = \ figures/hoge1.jpg \ figures/hoge2.png Next go to docs and do ruby checknew.rb Then an entry for Hoge-HOWTO is added in docs/configure.in and docs/Makefile.am. In docs do $ ./autogen.sh $ make to sythesize html and txt under docs/Hoge-HOWTO/ja. If you confirm that there has not been any errors doing make then do svn commit. To edit the existing documents, do svn update to renew your repositoy up to the latest. When you finish editing, add your revision history according to the format. After that check using xmllint and if there is no error, do svn commit. DocBok is a set of tags that mark up logical structures of documents. It is not designed to control appearance of the documents. <para></para> Suppose you thought you put a line feed doing the above. Now it may be displayed as you meant it to be but on the other style sheet it may use different color to recognize separate paragraphs and some may use sound even. With the command above, it can only inform that an empty paragraph is existing there but nothing else. And come to think of it, html is also similar in that regard, originally, that is. Comment format <!-- ... --> seen often in html is not a comment tag which starts with <!-- and ends with -->. A comment is a comment and inside a comment, -- should not be used as stated in the xml definition. <!-- hogehoge fugafuga -- buroro --> So a comment like above is not valid. Seems it has become strange but originally here were sentences that were heavily influenced by the law "xml is not sgml" ... In html, an empty element, e.g.,br tag must omit an end tag but an end tag can not be omitted in xml. To rephrase it, in xhtml you must write br/ for br. It's the same story here. In html you can omit "" to pass a value but in xml you can not omit it. Therefore, <sect1 id=hoge> would be a mistake. More likely, certain rules have been set for what can be omitted in html. A browser that can accept any kinds of syntax should be regarded as abnormal. Xml distinguishes upper and lower case of characters in tag names. <sect1> .... </SECT1> Above is incorrect as setting an end tag of SECT1 without a matching start tag. Weeeell, say SECT1 as a tag is not defined anywhere in the script shown, so it is a mistake to begin with anyway. This document has been written based on OmoiKondara-HOWTO by the Kondara Project with additions extended by the Momonga Project. We thank Mr. Shingo Akagaki, the author of Kondara-Document-HOWTO, also the Kondara Project, and the people that maintained the documents at the Kondara Project. This document comes with no warranty. The author of this document can not be held liable under any circumstances for any direct or indirect damages resutling from the use of this document. The copyright of this document belongs to the Momonga Project. The distribution license of this document is subject to the OPL, (Open Publication License), excluding license option A and B. For details on the OPL, refer to http://www.opencontent.org/openpub/. Japanese version of the OPL draft version 1.0 by Mr. Masayuki Hatta is available at http://www.opensource.jp/openpub/. To redistribute this document, please retrieve the latest version from http://www.momonga-linux.org/docs/Members-HOWTO/C/.