 Yeah, this is in fact a additional talk to one given two years ago by Brandon Robinson who did Talk about writing man pages using the classical Unix toolset for writing manual pages that is a rough format and And one year later Lars from Finland wanted to have a talk where he wanted to present an alternative of writing man pages using doc book XML and That somehow didn't happen. So Because I had the same idea at the same time I said, okay, when one year later, I will do the talk. So I'm doing this now Writing manual pages without having to learn a Little bit outdated Text format so the history of online manual pages just very short the first online manuals appeared in In 1979 before that all computer manuals or software manuals were printed manuals So a lot of that trees hanging around your computer since 1979 they were online available The GNU project later invented in hypertext alternative to manual pages called info They had also a little bit of criticism towards the style of man pages because it's very fixated format and They had other ideas on how to do it since the early 90s a lot of online manuals in the Unix and also in the Windows world is based on HTML and We have certain set of HTML based help systems and the Microsoft world you have CHM or HTML help We know of Java help We have Yelp and GNOME. I Think Eclipsa help is also based on HTML and so on and we have a lot of other online Help formats mainly ASCII text readme's and PDFs which are In fact more for printing, but sometimes they are the only available online help So what's so special about manual pages compared to other help formats? For us for Debian manual pages are special because they are mandated to have them for all executables and We should have them for file formats protocols and whatnot. So we as Debian say we Like manual pages if you cite a man page You see this very often there's a name of the command or of the file format or whatever and then in Races the number of the section so a number from one to nine You read manual pages using the man command, you know that and there are other ways of accessing manual pages like d-help Woman which is an inside of e-max a manual reader or Yelp and GNOME and Other programs as well Manual pages are reference documentation. They are not meant to be a tutorial or how-to Sometimes they are but it's not the original idea and sometimes It's quite hard to get along with manual pages for example if you can't remember the name of a command you can not call the right manual page or Sometimes you try Man-k to to find something and sometimes it works and sometimes not or If you are looking for an example how to use a command, but the manual page is Just too short or too complicated or does not include the example and so on and all main pages are Located under user shaman with Subdirect eras for the section or for the language and then the section if it's not the C locale or English so the Layout of a manual page you 1000 times saw this Always starts with a name of a command or a file format or whatever Then there's a short synopsis giving the Options in a short way of a command for example And there's a description more prosaic. What is this command meant for? if you're lucky there's an example section if you're more lucky or it is not empty and See also is also very popular other typical sections include license authors known bugs and so on there are Sections in the manual the first section Is about executable shell programs for every user Where you find the manual page for common commands like a less You have a second section about system codes a Third one about library functions For us about special files like device files and so on five about file formats configuration files and so on six games Seven is Stuff like UTF 8 format on ASCII table or things like that That things that do not belong to other sections 8 is mostly for the root account system administrator commands 9 is not a classical section. It's I think it came with Linux It's about kernel routines and so on and there are also more sections for example for Tickle DK has some sections with an edit and and so on so Manual pages are formatted in the rough format. It's Yeah, a markup language very much like tech latex xml html and so on but older and it is Really Yeah outdated I would say for nowadays it's a format which is In my opinion not very good to read or to learn and a little bit cryptic if you're used to it Then it's fine, but I think It's relatively hard to get along with it nowadays there are two Flavors of rough and rough is for the screen output and teeter off for printing and In former times all the unix manuals. I don't know what I was now But the classical unit man Unix manuals are printed using teeter off on some lino type machines also and Special editors nowadays to edit man pages if you are not so confident with Rough men edit for example The other way I want to present here is to generate Rough manual pages from other formats so that it becomes easier So short diversion. What's about manual pages in Debian? We have many Manual pages really a lot I Didn't count it, but it was much more than most other distributions, of course we have more packages and We have them in multiple languages Because manual pages are mandated by our policy Package maintainers always have written missing manual pages for Commands gave them to upstream so Upstream very often accepted those manual pages. So if you are on the Susie machine or redhead or somewhere and Use a man page there you will find very often this man page has written for the Debian system because no manual page exists before and so on the quality of manual pages both the upstream manual pages and the Debian ones The quality is Very different sometimes it's completely useless like this manual page has written and look in the read me and no further information and sometimes are really good Presenting all necessary information in a nice way. So to arise greatly One thing about utf-8 with the latest release edge We want to have everything in utf-8 manual pages are not yet in utf-8 or sometimes are but mostly not This is because in manual pages. You cannot state which encoding you are using so The encoding is derived from the language actually by Roth and and Gerov had problems with utf-8. I heard that this is fixed now, but I'm not sure about this We could try to go to utf-8 with For the manual pages But there has been some bad experience I think redhead delivered Japanese manual pages in utf-8 that were actually not readable and I think Ubuntu had also problems Changing the Spanish manual pages to utf-8 without checking first whether it works and it did not There's a question my understanding is that the utf-8 patches for graph were Basically rejected by upstream because they were really heinous and didn't really fit very well And upstream was going to try to rewrite graph to support utf-8 properly and I don't believe that work has ever actually finished It's not yet finished you believe okay, so There is the idea of having This as a release goal for Lanny, but well, I mean it's maybe not so important to have this stuff in utf-8 But it would certainly help a little bit currently we use for example, you see JP for Japanese and ISO 8859 one for European languages of Central European languages So some things I came across and they've been manual pages is that we have see also Sections that point to other manual pages that dot do not exist in Debian at all It's not that they are just not installed. They do not exist this is mainly sometimes an upstream manual page is taken and There's a see also and nobody checked whether this manual page Actually exist or maybe it existed at one time, but has been removed since and so on yeah, sometimes there are examples sections that are empty or useless and Yeah, this is something I'm not sure about whether it's good or bad in some manual pages There are references to other systems or not Debian Then the manual pages on a Sun system you have to do it that way and on HP It's that way and I'm not sure whether we want this Sometimes it might be helpful this additional information for example If I know that a command behaves differently on another system, it helps me to write portable Shell scripts or something on the other hand at the men some manual pages are cluttered with information that are Not needed in Debian. So this is maybe something That is not really clear There there is Concept called profiling. I come to that maybe later Where you can write a source document with paragraphs About specific systems and generate later a manual page Where only those paragraphs are in that are for your system So you could have for example an HP specific Section in your document, but later in the printed manual or online manual It's not visible on a non HP system and so on. I Really cannot say a lot about English style. I'm not a native speaker. My English is flaky so just a few points I found in typical how-to's on technical documentation a Manual page I said it before is a reference documentation not tutorial how-to whatever so if you write a man page try to be brief and still complete technical documentation including manual pages should Be written in a neutral style. So not Including the person who actually wrote the manual page or the code so if you write manual page in English, which is almost ever the case when you're writing a manual page for upstream then Try to get some English person to review it a Thing I came across a couple of times is hacker dragon or some jokes that are more insider jokes for geeks a lot of manual pages are meant to read by end users that are not geeks and they do not know hacker dragon and It's just confusing so Also cultural references to certain things like our favorite science fiction series or To Monty Python or some things. I really like those but not everybody knows about these things and then Might be confusing so better not do this in a manual page Yeah, and of course be friendly also on the manual page try Not to include Flaming against other Software or whatever There are a number of style guides online I found the one by Fedora I found the one by Ubuntu and I found references to the one from GNOME, but I did not find the actual GNOME document it must have existed Sometime, but the online link is broken so Maybe somebody can find it using Google or whatever I Did not find any rules by Debian. I do not know whether we never had them or Whatever If anybody knows about Debian style guides for documentation Please speak up. So the format I Present for writing manual pages is dog book XML The slides here just looking at are also written in dog book Dog book is a semantic format. That does mean it is not about the presentation of information But about the content for example, if you type a file name in dog book you would probably Mark it up as file name and not as let's say typewriter font ten points or something Dog book XML is the standard documentation format of a number of both free and non free projects The Linux kernel documentation uses dog book Not only dog book but also dog book GNOME KDE. I think in BSD it's also, but I'm not sure about it It's used also novel Sun O'Reilly and a couple of other companies The idea of dog book is that you have a single source format and can present all kinds of Formats from that single source for example html PDF all kind of html based online help formats manual pages of course and There is a new round trip Style sheet that generates Open document format and even Microsoft Word format from dog book and is able to Get these maybe change documents down then back to dog book You have a lot of tools dealing with dog book for example tools generating dog book from source code tools to generate all kinds of output format from dog book Specialized editors for dog book or similar formats and so on So if we talk about manual pages there are a number of tools to generate manual pages from dog book The best one in my opinion is using the official dog book XSL style sheets together with an XSLT processor. I always use XSLT proc because it's Very good and very fast. There are also Java based ones that are free, but I Mean maybe because they're based on Java. It's a little bit slower Then there is a tool called dog book to X which is a little bit older but has the nice property of Generating info pages. This is useful if you package something for e-max for example Then you may want to have online documentation in info format because that is what e-max users expect There's an older tool. It was I think one of my first Debian packages About eight or nine years ago. I don't remember exactly that deals with the old dog book sgml format and There's a reverse tool that Produces dog book from manual pages by Eric Raymond. It's called dog lifter and I tried it just now It works very well. It just Crashes if you try to Generate dog book from the man page for the man command, but other man pages work well so There are some examples for how a manual page in Dogbook looks like I will change to a decent to a decent editor to show that so That is basically how this dog book man page look looks like this is the manual page for aptitude and As you can see it Has a lot of XML mark up which is Very verbose unfortunately, but is much more readable than their Corresponding and rough output. I will show you as I'm for comparison now So this is another man page because I didn't have the aptitude one here, but as you can see the XML Format is much more verbose, but in my opinion also much better readable and possible so of course XML is easily possible in all kinds of scripting languages because XML support nowadays is a built-in features of all modern languages libraries You can have also man pages for Functional references, but I don't show this now that that becomes too boring, but if you want to Really go into the matter look for example at the documentation of Drillip the library under under the hood of GTK toolkit all Functions there are described in dog book XML and you can easily look how they do these things So when I looked at the manual pages for example for aptitude of the drill it took toolkit and so on I came across a number of things which I didn't like So first if you write a manual page or if you have snippets of XML and additional files please Use always valid XML that includes this nice header line. You'll see in all XML documents starting with less than question mark XML and so on version 1.0 or whatever and If this line is in and it's valid XML you can use any kind of XML editor to edit it Or we are or whatever, but if it's not valid XML then at least the XML editors will maybe not be able to to be used for this Another thing In the ref entry info use if it's a debian man page use something like called name debian Or if it's a GNU man page then called name GNU and whatever Because this will show up in the manual page in the I think lower left corner or so Which is a standard way to do it if it's not in there Yeah Then it's not clear which is a source for that man page. It's also useful to include the Date for the man page. Otherwise the build date will be used, which is quite a few of us If you provide a man page for an upstream package, it is the best just to use the same license as the program has so that For the man page, there is no different Licensing scheme than the program which does not make sense or use 3 pl or use Dual licensing or something But it would be a little bit bad if you have a program under 3 pl and then put the manual page under a stricter license For example to include one XML document into another Use x include not system entities Because this is much more flexible and it allows to include valid XML documents including the XML header into another document and Not only snippets of XML that are not valid for their self Well with the markup in doc book. I said it before it's very very verbose. So Don't overdo it mark a final name as final name that's fine, but Maybe it's a little bit overdone to mark a file name as device file and or directory. I mean That is maybe a little bit too much So there's a lot of criticism against doc book and I really can understand this. It's really verbose all element names are long it has hundreds of elements hundreds of Attributes for those elements. This is Little bit hard to cope with when you start It's XML a lot of people do not like XML If you do not like XML, don't use doc book the three tools to generate PDF from Doc book if you want to use PDF for example, if you want to print out a manual page or if you write a book Yeah, the three tools are all always a little bit problematic if you are using English or a Central European language, then it's relatively fine But as soon as you start using Asian languages or right to left then it is more difficult so mainly fob db latex and XML rough other ones I've tested and Here and there there always are problems So some conclusions Even if manual pages are real old format. There are good reasons to provide them Mainly for us. They've been it's our policy There's no reason anymore to learn rough in my opinion Maybe with the exception if you really have to use it or if you're maintaining GROF using doc book XML to generate Manual pages is maybe not the easiest way, but it's not too hard and You can easily have a lot of examples in the libtree lip, libtree decay, aptitude and many other packages doc book is a very acceptable format and And is used in a lot of projects You can generate all kind of output from doc book So it's really flexible. If you write manual pages in doc book XML. They will perfectly integrate with other documentation Books written in doc book or articles you can easily include it in a book You can include easily a single paragraph in a book Without having to cut and paste just by using x include That's it for now I'm open for questions and if we have some more time I can show for example XML editors or tools but Only if their need arises Hello, my name is Silvan Lagerl in fact It's not a question. It's a suggestion because I use a doc book for Doc book XML for all my man pages in all my package and it's great. It's really great because I I switched to SGML doc book to XML doc book and it's a thing which is very powerful I just want to spot one thing. There is a thing. There is a tag which is called command synopsis Okay, this tag in fact describe all the option you have for the command for example if we go back to the aptitude example you will see that This command synopsis include All the arguments you can have it's just right here. You see command group and everything you can have It's very powerful Because if you pass this kind of thing you can generate auto completion bash script Just to give you an example It's powerful. So I just write it's a shelter to transform this and you got You got your bash auto completion script for free So it's great. Another point I was not at the beginning of the comp. So I don't know if you talk about these tools is That you can easily Generate PO would have XML doc book using PO for are you can just Generate all the string from the from the doc book XML and you can easily and it and give it back to the translation team and You will have Something like all your man page translated to French English French German and also language. So it's another point and Last point just to make my own publicity I'm working on a CDBS class Maybe people know about CDBS Zire that will just you will just have to give the root main page name and it will just take the main page and run XSL tape rock using the book XSL To generate main page and put it in the right place and everything like that. So Here is my own publicity and So for now the CDBS class is not shared But if people want they just have to contact me. So similar legal. I'm a dbn developer. So Okay, we'll talk after Someone want another question a few years ago and DH make which creates Debian package examples created doc book SGML example files is this changed by now or should this be changed if XML is much better than SGML. I Think it now creates both However, I would suggest to drop the SGML because it's more or less dead in the dog book world Or it's it's really completely dead in the dog book world. So we could drop that Okay, it's a good search. Maybe we could file a which list back or something Yeah, I would like to see the examples of editors and different tools that you've used How many minutes do we have left so I would show it here so if no other questions are I would take the last five minutes to show some dog book editors and and Otherwise I could throw them later somewhere in the cafe or so Okay there are Two kinds of editors for XML The one that are source code based but really help you with the editing I personally use emacs But that is something I would only suggest for people who are already used to emacs If you're a Wim user, there is something similar, but I do not know it because I use emacs so What is nice about those editors that they are context aware? For example, if I go to a paragraph Inside the paragraph certain elements are allowed and I Type control return and it gives me the list of Elements allowed at this exact position So for example, if I use address Then I can now try to look which Attributes are allowed and it only shows the attributes belonging to address art is mainly used for For profiling purposes, for example, this is only for AMD 64 it doesn't make any sense now but you get the idea and inside of address for example only address created information is allowed and so on so You can have this within emacs And I believe also within some specialized editors and somebody told me that Wim also supports such a mode any Wim users here that can confirm or reject this idea No Then there are graphical editors. I will first present the free one then a proprietary one Here's another Source code oriented editor. It's called ml view. It's Economic thing. I didn't use it myself. I just opened it here. So you can try it Sorry, that was the wrong one I here this is Amaya Not the Debian developer, but the editor Amaya is a graphical editor for XHTML and dogbook formats and other XML stuff You can see this is a aptitude manual page again, and it looks a little bit like it's Yeah, here here buff. It does not look really good, but it's a little bit like what you see is what you get but with dogbook another editor, it's non-free I Have to say this But it's nice and maybe sometime we will Is it xxe It's written in Java. I've used this in my former company under windows even But it does run in Debian as well It takes a long time to start up because it's Java, but then It's really nice for example, I Open up the Oops Yeah, I see I Did something wrong what you can have also is dogbook is having a CSS style sheet attached to it which makes it possible to view the dogbook XML in your favorite web browser and it looks Like printed or something, but it's really only the dogbook XML. It's not changed to HTML Or something. It's just with the CSS styling for the dogbook XML source and That unfortunately xxe didn't like so I remove this information Where is it? So close. Yeah, now it works. So this is another what you see is what you get style of editor for Dogbook The only thing I do not like about this editor that it's non-free unfortunately, but it's free as in beer Have you used open office for editing dogbook at all? I didn't try it But I think the new round trip style sheets allow to generate Dogbook from open office and the other way around but you have to use certain styles for dogbook In inside of open office. I know that there are a couple of bug reports about this because this round trip style sheets are quite new so a Lot of people work on this Stuff and round trip is meant to be used both this open office as with Microsoft office Okay, so I think Get some useful state later there used to be another XSL transformation, but I as far as I know it never got really well and with the new round trip style sheets the Development does not go on on the old one as far as I know. Okay. I understood open office could edit dogbook files directly Yeah, I mean it it depends if you work together with people who are not used to working with XML source files But are used to using a word processor like open office, then it is really good thing to have To have it. Yeah, you just have to kind of control your styles. Yes Yeah, I think it needs a lot of discipline. Yeah Thanks Well, I just want to give a negative feedback feedback on a tool which is called a conglomerate This could be a great tool, but I think it has never been finished So if you like bugger, you can try conglomerate, but if you want something really ball I don't I suggest you not to use conglomerate for editing and What what edit on conglomerate? Yeah, no it I tried it out and it is very buggy it crashes and it it has still a long way to go and You also showed ML view and in my experience ML view is very good for viewing But as soon as you try to edit it just dies Here's ML view. Okay, any more questions we are done and I Think the The other speakers are already here. Okay. Thank you for attention