 I don't think I need to introduce the next speaker very long, because you all know him. Our beloved dictator, Mr. Brandon Robinson. Yeah, you're in for Nixon now. Okay. Well, just as a word of preface, when I originally submitted the abstract for this talk, I thought it was going to be for a 90-minute workshop. Sometime after that, the organizers decided there weren't going to be any 90-minute workshops, so there is more material, even after I cut it down a little bit, I think, than we can fit in. So, if I start going too fast, you know, raise your hand, stop me, and I'll slow down. Yeah, very funny, Jimmy. As fast as you talk, but Jimmy Kapliewicz, SPI treasurer, is here, so get your money from him. The checkbooks are in my hotel room, so. So yeah. Okay, well, I'm Brandon Robinson, and I'm here to talk about man pages, and you may provide your own alternate expansion for the F in the acronym, if you like. I'm going to cover a few areas. I'm going to talk about why I'm giving this talk, why you should care about it. And I'll move on to some basics, which will be more like how to read a man page in source form, so that we can then move on to understanding how to write one effectively. And that's man page tips and tricks. And then there are some issues surrounding man pages that don't involve actually editing the source file, the dot man, or sometimes they actually have the suffix number in the source distribution. It just depends on what you're doing. But ultimately, we have to get down to things like, gee, what should the copyright and license be on my man page? And how do I actually get it installed reliably, especially if I'm using the alternative system and I've got a command that uses alternatives and a man page for that command? I don't know, but if you're like me, you've been annoyed consistently over the years by getting these spammy mails from Cron, usually weekly, from Mandi Bee complaining about dangling sim links. And this is usually because someone failed to do the right thing in their post tensed or their pre-rem script. So I'll talk about how to avoid that. So let's move on to the first item here. Why should we write manual pages at all? Well, the most important reason, as far as I'm concerned, is because we tell people to read them. We have that acronym, RTFM, which I riffed on for the title this. We all know what that means. Read the fucking manual. It's not very nice to tell people this, apart from the profanity in it, actually obscenity. There is a distinction. It's not very nice to tell people this if there is actually no manual for them to read. And sometimes we tell people to RTFM even without knowledge for sure that the man page in question actually exists. So that's not too cool. We should be nicer. And besides, policy asks us, I'm sorry? UTSL? Well, yeah, but not all our users can be hackers. So I did an experiment just on my iBook. And I had a little shell script that went through every file, really, in sbin, bin, user sbin, and user bin, and took that and did a man-w on it and checked the exit status. So I got better statistics than I was expecting, really. That's pretty impressive. But then I only have stuff I really need on my iBook. My home box, Sisyphus, is considerably more crafty because it's got lots of disk and I just put any old thing on it and then never take it off. But still, that's over 10%. So we could do a little better than that. Yes, sir? I didn't check that. I'm not sure. The question was, sorry, I'll repeat the question. Let's see. Sorry, your name batch here. Per Olofsson? Yeah. Okay. Per had a question. How many of these pointed to the undocumented man page? Actually, I think the answer would be none because if they linked to the undocumented man page, man-w would have exited with status zero. It would have succeeded. So it would not have been reflected in my numbers. So the figure could actually be higher than this. Ah, my pessimism is vindicated. So we've got at least 10% that don't exist at all. Now some of these will be false positives. You could make a case that, and I'm staying too long on this point, but you could make a case that some things don't need man pages such as, you know, desktop environment applications that will never be invoked from the command line for any practical purpose. Maybe you could make a case for that. But another reason to write man pages as you've already read ahead of me is that the man DB package which provides the man pager infrastructure and the command is priority important. It's almost always going to be around. Web browsers and PDF viewers often are not, or they require a GUI environment, and it's not a lot of fun. As I know from numerous users over the years, if your documentation is going to require a graphical browser and somebody can't get the X window system configured or the X server configured on their system, they've got a pretty serious chicken and egg problem. So it's good to have man pages. It's good to have something that will work reliably on a terminal, and man is that. Man pages are one of users' last lines of defense against frustration. You know, when all else fails, it'd be nice to have a man page there. And we should write them because they haven't all been written yet. And finally, of course, nobody actually reads any read-me's, as we know. So there's not a read-me command. There is a man command. Actually, there should be a read-me command that goes and looks in user share doc package for readme.debian. So somebody here who isn't through the NMQ yet could volunteer to do that. It'd be pretty simple. Just remember to write a man page for the read-me command. Why should we learn to write good man pages? Because many of the ones out there are suboptimal. My exposure to this fact lay in that I didn't know how to write man pages when I first started. I started looking to existing ones for examples. Well, I picked out I'm kind of random if they looked good and I learned some bad habits that I later had to unlearn. So I'm going to try to, while I'm sure, well, I know I still don't know everything. I'm not a 70s-era Unix hacker who knows Roth inside and out and Colin Watson, for instance, who unfortunately I don't believe is at the conference this year. He knows a boatload more about Roth and macro packages than I do. But I know a little and I'm going to try to communicate what I do know. People are generally unaware of conventions used by high quality man pages and so they go unwritten or they go written poorly. People are ignorant of the basic GNU Roth syntax, Roth, and the AN macro package. If you aren't aware, Roth, as I alluded to earlier, goes way back. The original program that it's descended from is called runoff, which I think dates back to the 60s and actually predates Unix. And one of the very early things that Unix time-sharing systems were used for. Yes, this is Lars, my uncredited, okay. He's getting ahead of me so it'll be ready when I get to it. Let's see, one of the first applications of the Unix time-sharing system is developed at Bell Labs was for document generation. So Roth was a pretty sophisticated system. Unfortunately, it had licensing issues as did a lot of the old Unix stuff. You're distracting people from me. I'm a prima donna, I've got to have all the attention. Anyway, I'm delegating some of the attention to him. So, almost fairly not altogether bad, yes. Excuse me, if anybody needs to ask. Microphone gets to you. Yeah, because of this. Right. If we want to have much posterity in our recordings for posterity, it's helpful for people to view the recordings to actually know what's going on. Which means you want to be on the screen sometimes and you definitely want to be heard. You want to make it to the soundtrack. So, and of course, if somebody can't get the microphone, I'll try to repeat the question. Anyway, I digressed into the history of Roth and I'm going to get off of that. It goes back a long way. GNU, as they did with so many other things, wrote their own and it's largely compatible. People don't know lousy, gruff, or A in syntax or usage of the system when they see it. And as a result, people are often poorly equipped to judge the output of engines that generate man pages from another source format. Lars Rosinius, this is a pet peeve of both of ours and he's been helpful to me in over the years and recently in developing this presentation. Doc Book to Man, which is probably the one best known to you, is especially bad with what it generates. It's just awful. I dealt with this at Progeny when we were documenting. I believe it was Discover and, oh my God, the output was just awful. It looked terrible. I mean, not only was it syntactically bad in source form, but the actual man page, as viewed by the user, was bad. It was ugly and unpleasant to read. And a man page that is unpleasant to read is less likely to be read. So, well, let's talk about what a manual page actually is. And now I'm talking here about the actual source file that is used to generate. You may not know, you may not be aware that there are multiple output formats that man pages can be used. We're most used to the terminal, but you can also generate postscript directly from a man page. And you can also generate an X window. If you've ever tried the dash capital X option to the man command, then you might want to experiment with that and see how things show up. It's nice, especially for font rendering and stuff like that. Man pages are written in the Roth type setting language, which I pretty much already covered out of order, as tech is. Tech is another type setting language. Type setting languages tend to grow macro packages. Like any low-level tool, people write macros to make things easier. And the AN macro set is the one that man pages use. The reason they're called man pages is because you select the macro package that you want with a command line flag to Roth called dash M. And then you specify, without any space, because this is old school unix, the macro package afterwards. So you type AN, so the command line argument would look like dash MAN. Now these days, Groff doesn't actually get invoked that way for historical reasons. It uses a thing called andock, which picks M-docker. Anyway, I said I wasn't going to go into it and then I did, right? Man pages use the AN and less commonly dock macro packages. Dock comes from the BSDs. So you'll see a lot of M-dock man pages on the BSDs, including the dock macro package itself. So if you man seven dock, you'll be able to see what this looks like. A man page is intermediate in scope between terse user documentation, like usage messages, which should be lean and mean. If for nothing else, if someone forgets to pipe it through a pager, it'd be nice for most commands to fit what they have to say, under one 80 by 24 screen. And of course book length manuscripts like the GNU, Emax, Lisp reference manual, which I think is two volumes or something like that. Something that huge is not appropriate for man pages in my opinion. And in practice, most people don't write man pages that huge. Where are man pages kept? Now here, I'm going to warn you. I'm going to stray a little bit from telling you things that are factual and get a little bit into areas of opinion. I like the idea of a fairly tight coupling between the sections of man pages and where you find the things they document on the file system. Not everybody shares this kind of militant mapping philosophy. So in many cases, you won't find things quite this simple in the Debian system. And it's not necessarily a bug, I'm just kind of a Puritan. So with that caveat, generally section one, as you may know, there are eight sections in total. I'm sorry. Well, nine's not used on Linux. So what section nine was used for historically was kernel internal interfaces. And these days, I guess you have O'Reilly books and Linux weekly news to read about kernel internals. User commands are in section one. These are things that generally don't require privileges to use. Section two is the system interface or system call interface. So the C library doesn't provide these, or they're just wrappers around the actual system call interface. So these are services provided by the operating system kernel, fork, read, sbreak, so I guess that's set break for BDL would know he goes back far enough. I don't know the provenance of some of these names. The library interface, for instance, the C library is most commonly thought of as being documented in section three. But any library can be documented there and often is. Malik, printf, those are C library functions. And xtcreateManageWidget, which as you might guess from the name in my history, comes from x, specifically the xt library, which underlies Athena and less thief. So section four is the device interface. Device nodes are often found there. I meant to check before starting this to see if there is actually a null man page. But in principle, you could man null and read a section four man page about the purpose of the dev null device. File formats, this is, I'm sorry, did you have a question? Okay, I saw your hand move, so file formats. This is a section of the manual that a lot of users don't seem to know about, which is a real shame because there's a lot of good information in section five of the manual. So someday when you have time or right now even LS user share man man five. You'll see a lot documented there that you may not have known about. And it's good stuff. So fstab for instance is documented there xorg.conf. That's a way of teasing you because it's not unstable yet. I didn't, I can't, we're getting away from x386. I just couldn't stand to put xf86 config in this document. I'm trying to look to the future, so in the present for that matter. Section six, games, I think it's kind of silly that this was segregated off. But it was, back in the days of time shares, it was important to be able to switch off the games or switch them on at night when the system wasn't going to be used. It's kind of an anachronism, but there it is. And it would probably be a big pain in the ass to reassign that number to something else. I've really got to pick up the pace here. Administrative commands, SBIN, user SBIN, much like section one, except these are things that typically require administrative privileges of some kind. One thing to note is that non-English man pages are often available. And you will find them right under user share man in the local named directory. And those reproduce the man hierarchy, man one, man two, man three, etc. Did I forget seven? Missile, okay, it's on the slide, I didn't talk about it. Section seven is pretty miscellaneous. I think historically it may have been used just for documentation of macro packages itself. I haven't been able to find a lot of information about this. Yes, that's one. It's just more of a generic stuff than just single command. Yes, I'll repeat. Wouter said that, for instance, you'll find an X man page in section seven. I'm repeating his questions. You'll find an X man page in section seven as well as section one. The one documents the command and the other documents the system. So there's a lot of high level information about the X window system that you can get if you type man seven X. Those are three arguments. So yes, thank you for catching me there and having me go back and talk about that. So let's get into the meat. What does a man page look like? Line's beginning with a period, aka full stop. I have this propensity to use actual UTF-8 names for or unicode names for things. Our control lines, they're also called requests. So we see a thing here called .sh and then synopsis afterwards. And then a line that says one, two. And then a line that says .lowercase, br. And that's not a reference to myself. And then three on a line. In the above, synopsis is an argument to the sh request. Now, it happens to be rendered, but that's just because of the nature of what the sh request does. You can have requests that don't reflect something that gets printed. For instance, there's a request that sets the distance between paragraphs. So if you said .pd5, you wouldn't see five show up in the corresponding spot in the generated man page. Instead, it would make the distances between your paragraphs larger. So just think of that as kind of like a function call, instead of some piece of literal text. And that's gonna come back in a moment. I'll dwell on that a little bit. Everything that isn't a control line is a text line. So if Groff can't interpret it as a control sequence, it'll try to write it out as text. Character sequences beginning with a backslash are escape sequences. Now these are separate from the requests that are on a line starting with a dot. These often consist of a left parenthesis followed by two characters. Groff is significantly more flexible than that. But for historical traditional reasons and so that your man pages will render on more implementations of man. You often see just this kind of abbreviated strange syntax where you have a backslash and then two or three characters. So for instance, copyright backslash open parent, that's correct. There's no closed parent. CO gives you a copyright symbol, 2005 quucks. And then backslash lowercase f, capital I, and then immediately italics backslash f, capital P, Inc. Now I'll explain that a little more later, but as you might guess, that puts the word italics in italics. And yes, it is ugly, and we'll come back to that too. The Groff 7 manual page, again, people often overlook sections that aren't one or eight, contains detailed discussions of control lines and escape signals as much more detailed than I could go into this presentation. Groff is pretty forgiving of poor invocations of requests. So if you give a request fewer arguments than it expects, it tries to muddle through. Sometimes this will throw a warning. I don't believe I've ever seen one bust a man page. Generally, well, I mean it may look ugly, but you don't exit with an error. Instead you just get poor rendering and it pushes on forward. Arguments to a request in excess of those required are ignored. So put all the garbage you want out there if it's not defined to accept those arguments they're thrown away. Use double quotes to include white space in an argument. So for instance, if we go back to the slide and say that SH synopsis, now the SH request takes one argument. So what happens if my section heading, which is what that is, is called say application usage. That's two words. Well, I shouldn't say application usage just as is. I need to put it in quotes just like you would quote at the shell prompt, an argument that needed to have embedded white space in it. Now, again, graph is forgiving, especially for the .sh request, because so many people forget. Actually, the real example is C also. Most man pages have a C also section at the bottom, and it is very common to see the quotes missing from it. But it's two words. Remember, just go ahead and quote it. Because not all requests will be so forgiving. To begin a line with a literal period use the escape sequence defined for this purpose. Actually, this is broken, I confirmed it right before the talk. This is documented to work this way, but it doesn't actually work. Instead, the lines treated as a comment, I don't know why. Does one of you? No, okay. Well, like I said, I'm not an expert and the documentation did say that should work. So hopefully I'll get time to file a bug and someday Colin will get to it. To input a literal backslash, this does work. Use the escape sequence defined for this purpose. So it's a backslash and open parent. This means that a special character is being defined, as it turns out. And RS, I guess the mnemonic for that is reverse slash often indicates a new line. So put a new line at the end of every sentence. This is another one that almost nobody knows about. But like tech, the type setter knows about the difference between a space, between a word, and the space between sentences. Yes, this is nitpicky stuff, I'll get into more high level stuff in a moment. I'm giving you the syntactic basics. This tells Graf to use intersentence spacing, which is, I'll be happy to eat that when it's good and cold. My pizza, now all the toppings are slid over to one side. Okay, all right, yeah, I was finishing this up. So I didn't get to go to lunch, so ordered pizza. But thank you. Intersentence spacing is important for proportionally spaced output formats. And there's a more important reason for that. It makes life easier for translators. Most languages, in fact every language I've heard of has a conception of a sentence. So you have these logical break points. If you run all your sentences together, then viewing diffs becomes more of a challenge. So another thing to keep in mind is don't put blank lines in your man page. That is beginning of line and then nothing, just immediate new line. So backslash n, backslash n, and if you viewed it with octal dump, O-D. Don't do that, there are better ways to get spacing. Like the .pd request I talked about earlier. That's capital P, capital D. And in general, I don't find much use for adding a bunch of extraneous white space in man pages anyway, even when you do it the right way. Use the null request, a lone dot, to pad your man page if you need it. If you wanna put some space in between things, so you can read it better. Or if you find it might make the page more maintainable, absolutely go ahead and do that, just do it the right way as shown. As with any civilized language, Groff supports comments. Any language that doesn't support comments is garbage. Anthony inspired me to just be a real curmudgeon today, I think. The backslash double quote begins a comment that runs to the end of the line. Much like forward slash forward slash and C++ and now C99. So for example, we have something here C spot runs. And then I immediately follow it with a backslash quote. Note to myself fixed grammar. The XXX fixed grammar won't show up in the man page output. And then the way to do a comment on a line by itself is to have that kind of null request, the lone period, and then follow it up with the comment character. So this isn't, this is really two pieces of syntax here, not one. Okay, this is some more, now we're gonna get into some more fun stuff. We're gonna move up from that low level and start building upon what we've already covered. .pp is a new paragraph, there are a couple of aliases for it. But .pp is the most commonly used and I encourage you to use that one. .tp is to define a new paragraph with a tag. You'll be using this all the time when you're documenting things like command line options, because to get a layout the way most traditional, most man pages, almost exclusively all of them, the document commands. You get a level of indentation that differs for the description of the option. So the options here and then the description of the option is indented a little bit. And that's the way to do it. And the .b option or the .b request you might guess means bold. But we'll get back to that. There's a mistake here. There should be backslashes in front of those hyphens, sorry. .rs begin indented area, .re should be end indented area, sorry about that. .b u as you see in the example, that's a bullet. There are lots of interesting symbols available. And as people use UTF-8 terminals with good fonts more and more, these things will actually show up in the man pages. These all have down conversions to ASCII. They'll all be rendered in ASCII in some crude reduced form. So go ahead and take advantage of it. It'll make things look prettier when the man pages type set. And it'll make them, you'll have more distinctiveness when you're viewing things in a UTF-8 terminal or in hard copy. Okay, people love to fool with fonts in their man pages, in part because it's fun and in part because it's often important to set aside things that are going to be substituted or things that are meant to be typed literally. Now this is not sophisticated. These days we have semantic markup as in XML. But these are the old days when you just used presentational markup. So I want this to be bold instead of this is a keyword. Uh-oh, the cards are coming over. And I'm how many slides through? Okay, b.b.i, bolder italicize all arguments. There are ways to alternate bold and Roman or normal upright. And this just means every other argument uses, like for instance with br, the odd numbered arguments to the request are bolded. And the even numbered ones are upright. And we'll see examples of these in later slides. I recommend using these macros and preference to font escapes wherever possible. Remember that backslash lowercase f and then capital I stuff. That was kind of ugly to read, wasn't it? These are better. You can put the escape in the middle. It doesn't cause a line break. So, but you need to know the font escape sometimes as we'll see. And these are what those mean. Switch to bold font, switch to italic font, switch to the Roman font, and something that is underused, switch back to the previous font. It doesn't make a lot of sense to literally go to Roman when what you really want to do is treat your fonts like a stack. So push bold onto the stack, pop it off. Push italic onto the stack, pop it off. So I encourage the usage of dash f capital P. Now this is something that almost everybody screws up. Dash is hyphens and quotation marks. And in fact, LaTek was kind of giving me a bit of grief when I was trying to get these characters exactly right. So they don't actually present perfectly. But I think you'll see what these are from context. And that just means that the directions on the single quotes down there are wrong. They should be different. But anyway, a dash all by itself is a hyphenation dash. Now when you're in a UTF-8 environment, this will render very narrow. You can use a backslash open parent en for n dash and em for m dash. And if you don't remember what those are, they're covered. An n dash is for a range, generally. An m dash is for a break in discussion. And then backslash hyphen is literal hyphen minus. 10 minutes. I knew this was going to fill 90 minutes. And I only have 45. It was probably a backwards decision of the language designers to not swap or to have the hyphenation dash in a literal one this way. But let me tell you why it's important to use the literal hyphen minus instead of the hyphenation dash. Because when somebody's in a UTF environment and they're searching the man page, well, when they hit slash and type a string to search for, or a reg x, and they type a dash, it's only going to match the literal one. So if you've documented a command line option, for instance, like dash dash help and somebody's looking for that, and you use the wrong kind of dash in your man page sources, they won't find what they're looking for. And it's because you use the wrong type of dash. As I said, this was probably a backwards decision. But if you want to help people out, this is the way to do it. Use the right kind of hyphen. You can get left and right single quotation marks, and you can get the neutral straight up and down ASCII quotation mark. That's why I mentioned the code points here. These are code points in ASCII, in the ISO8859 family, and in Unicode, of course. Because those are steadily building supersets in the first 128 bytes. Left and right double quotation marks. You know, use these to set aside your text so that people can tell when something's meant to be interpreted literally or not. Critical man page macros, there are two that are essential in all man pages, because man DB uses them for indexing. The first is TH, which declares most of the basic information. I really shouldn't just read the slides to you. Let's try to pick up the pace here. Source and manual title are inconsistently used. The really important ones are the first three, and probably really just the first two arguments to the TH macro. Put the command name in there, and put the section in there. Most man pages capitalize the command name. I think that's a silly convention. So again, I'm going to deviate from practice here and give you a recommendation. We have commands that switch case in the name. So it would be nice if what we're documenting actually showed what you're actually supposed to type, as opposed to something that's done up in uppercase for the sake of presentation in a printed book. Man pages with the same name can be disambiguated by the section name. Now, they may all go in a directory called man3. But for instance, you can have a section called 3 Perl or 3x11 to indicate the source of the man page when you need to disambiguate something. This is how you avoid collisions in man page names. So if you've ever had to grapple with this problem, use this technique and you'll be fine. Now remember, the file name extension, that is the part after the dot in the man page name, needs to match the section as declared here. Don't worry about the directory that the page gets installed to. It'll go to man3, but the extension needs to match what's indicated in the TH request. The name section is the other essential part. And this gets screwed up a lot, and in Debbie and you will occasionally see bugs filed against this. This is the section heading macro as I already covered. It takes a string argument that runs to the end of the line. Note the hyphen minus. That's really important because Mandy B scans. It needs to find that hyphen minus so that it knows what to use for the description of the command. I think Colin, within the past year or so, might have made that a little more robust or maybe upstream did. But at least as of a couple of years ago, you could confuse it by using the wrong type of dash, which is why the man page is got, which is why the bugs got filed. Again, use correct casing here, even if you don't in the TH request. Now that is the convention. So I'm not making a recommendation apart from convention here. A command synopsis should document the command's name, operands, and options. I distinguish between arguments, operands, and options. Arguments are just things that are given to the command. An operand is something you operate on, and an option is something you don't necessarily need to have because it's optional. I'm a stickler for terminology. So we render the command name in bold. Now this one has a dash in it. I did this on purpose so as to again remind you of the importance of quoting that. If someone searches the man page for update dash gizmo and you leave out that backslash, they're not going to find it. So it's important to be able to search man pages, as most of you probably know. Again, note the escaped hyphen. Put the command name in anything to be typed literally in bold. I'm documenting convention here. Square brackets indicate five minutes to go. Optional arguments. An ellipsis, notes repeated arguments. Now you'll see I have a couple of quotes around the ellipsis. Can you guess why that might be? Well, I have a space there. And these will be run together. So the fact that I have separate arguments doesn't mean there's implicit white space between them. So if I want there to be a space after the word file and before the ellipsis, I need to put that in one or the other of the arguments. I mean, I don't think there's any difference between an italic space and a Roman space in graphs. So it doesn't really matter which one I use. And you use braces or curly brackets, as they're sometimes called, and vertical lines or pipe characters to denote that one of an exclusive set of arguments should be used. And I tried to pick an example we might most be familiar with. When you invoke tar, you might use, where are my hyphens? OK. I screwed something up in that. But there should be backslash hyphen before each of these. But as you know, you can invoke tar with create or list an archive or extract one. But you never combine any two or three of these. You only use one. And that's an important distinction. So to indicate that you have that type of selector or radio button, essentially, you use braces and pipes. I should note here that the stuff you literally type in is in bold. And the braces and pipes are not in bold. That indicates that you don't type them literally. If a command can be invoked in multiple incompatible ways, multiple lines can be used for the synopsis. There's nothing wrong with that. So for instance, in this example, which is broken across multiple lines, both to show you that it can be done, and there's an extraneous quote in there. But you can break it across multiple lines. Well, I lost my train of thought because I saw my bug. So shame on me for not proving more carefully. I've got a list of recommendations for man-page section headings in the various sections. Now these are executable commands. Now this looks like a long list, but I actually got this mostly from the single UNIX standard. And in my experience, I actually find documenting most of these if they're applicable to be pretty important. Names, synopsis, options, and description are found almost universally, as is see also and usually authors. The others are often left out, and I think that's unfortunate. An exit status section. Yes, is this four minutes? OK, thank you. Exit status, I mean, it's useful to know what a command means when it exits with status 10 or status 15. So it's a good thing to document. Input files and output files, if there are any. Diagnostics, that's the convention for describing what the error messages are that come out that you spew to standard error. It's good to document what those mean too. Asynchronous events, that means if you set up any signal handlers. So if you wrote a shell script that traps sig quit, for instance, I forget if you can trap sig quit. Let me try sig up. I know you can trap that one. If you have a signal handler, document it here. Consequences of errors, if unusual, one example I like to think of is if you leave crap in temp and you get interrupted, document that fact. Especially if you leave stuff in places that aren't slash temp, it would be more important. Or if you're likely to remove somebody's root file system if you're interrupted, it's a good thing to note there. Author or authors pretty much goes without saying and see also. Sections two and three, these are largely, thank you. These are, again, mostly used for C programming, although Perl has a lot of section three man pages as well. There's a slight difference here. Return value instead of exit status. But I mean, that should be pretty well understood people who are accustomed to programming. Conforming, too. This is a reference to standards documents. For some reason, I never see this in section one man pages, but I do in the libraries. Author or authors and see also. Sections four, five, and seven are pretty free form. You don't see, you see all kinds of things in here, very little is standardized beyond that. How to portably include URLs, I think I did actually make it more than halfway through this. Just include this magic recipe near the beginning. I'll have this available online so you can look it up. I don't expect you to copy this. Well, I expect you to copy it into your man pages, but I don't expect you to copy it now. How it works is you define a new URL macro that works like this, and it happens to be provided with the GNU-ROF. So that's what that last line is. We define the macro, and then we say if we're using GNU-ROF, load that macro file, and then that will just clobber the URL macro we defined with the real GNU one. And this enables your man page URLs to be viewable on systems that aren't using GNU-ROF. So which I just said, what's on the slide. So how to license your man page. Oh, where did the last section? If you're writing your man page for an existing piece of software copyrighted by something else, I think it's just polite to stick with their licensing conventions. I recommend this. Well, it's polite to place a manual page under the same license as a software. It documents, basically. And then I'm going to show a little heresy here and say I recommend this even for GNU software, whereas we all know they like to use the GNU-FDL. But they also hate man pages. So it's not so disrespectful to use the GNU-GPL for a man page, right? There's a more practical consideration, though. And that's the fact that the GPL and FDL licenses are compatible. It's redundant to say it well anyway. Incompatible in both directions. You can't just take text from the software and move it to the documentation and vice versa, unless you're the copyright holder. Or you have special permission to do so because the licenses are incompatible. I think that's a little brain damaged. Because ideally, don't we want something more closely approaching literate programming? So anyway, that's my recommendation for that. The other one would be to do a license. I personally have used the MITX11 and GNU-GPL licenses for man pages. Those are the only two I've ever used. Let's see, I'm going to run a little over. I think I can actually get through in five or 10 minutes, though. Is that OK? Who's in charge? May I have permission to run five or 10 minutes over? Oh, OK. Oh, OK. All right. The speaker after me is delayed, so I get to run long anyway, even without your permission. All right. So installing man pages that don't require any alternatives handling is not too hard, especially if you use Deb Helper, CDBS, or something like that. DH install man is a pretty nice command. I don't see Joey here. I'm giving him love, and he's not here to receive it. OK. Man pages using the alternative system require more care. This is that weekly spam from Cron that I was complaining about earlier. So I'm going to teach you now about how to avoid it. Generally, a man page that has handled by an alternative is not an alternative in and of itself. It's a slave, and if you man update alternatives, you'll be able to read about slave sim links. It's a slave to the thing that is actually managed by alternatives. So for instance, the awk man page, as Anthony covered in his talk earlier today. He was talking about mock and awk. If you have an awk man page, well, you'll pick one, and then automatically the sim link for the man page will be switched, because you wouldn't want awk the command, which happens to be mock, to be documented by the gaulk man page when you type man awk. That would be stupid. So if nothing else, it would lead to surprising behavior. So you need to register the man pages in the post end script of your package using the update alternatives command, just as you do for the thing at documents. And you need to unregister the man pages. And here's what gets people in trouble, for the remove and de-configure arguments only. And if you don't know what this means, if you have no fear, I'll show you. Now, the font gets a little small here, and I apologize for that. But I'm going to give you a real world example that I know works, and I've never bugged report or personally experienced any man page sim link breakage with x term. I've managed to get it right. The first time years ago. So I'm proud of myself for that. So that's very long. But as you can see, all it's really doing is setting up an x-terminal emulator alternative for x term itself, and then see that double-dash slave argument. Well, that's showing it to point the x-terminal emulator manual page to x term. Now, that's update alternatives install. In the pre-rem, we want to do a test. A post end story ever does one thing. It's supposed to get the package into a configured state. But a pre-rem does a few different things. And two of them are removal of the package and de-configuration of the package. And I obviously don't have time to talk about the distinction between those two. But if you'll just copy this recipe, you should work at least as well as the x-term package. So under those two conditions only, we want to deregister the alternatives. One of the others is upgrade. So you can see what happens here. You don't want to be deregistering the man page across an upgrade. And I made it to my final slide. For further reading, you can read man pages. I learned a lot of what I reported in this just by reading them. And I don't have any shame regurgitating some of it. Because one, these man pages get pretty long and detailed. They cover the fine details. And I wanted to extract out the highlights for you. And again, as I said, a lot of people don't know about section seven or section five. They don't know about the man pages that are there. And it's just unfortunate. So I'm hoping to open up a little bit of a new world to you in writing documentation. So I've been talking much faster than I would rather talk for a presentation. I apologize for that. I know not everybody here has English as a first language. It was to get through all the material. So as long as I have a little more time, yes, yes. Thank you. That should be in there. You don't have to install a man page to read it. I swear to God, you don't have to install a man page to read it. All it has to be is on the file system. You want to look at it, man-lowercase l, and then the filename. That works for anything. That's old school. Yeah, but that's old school. And actually, that bypass is pre-processing, if I remember correctly. So if there is table, or pick, or EQN, any of those pre-processed things, they'll be skipped. Well, yeah. But if it has them, it'll break. And you'll get weird output. This just works. So yeah, Wouter pointed out that you could use en-rhoff-man. And so there's what he said. And you can mentally insert that before the response that made no sense. So yes, about alternatives. Yes? Ah. Probably need to put it in a for loop. Oh, wait. No? Because you probably need to use xargs to build a command line to update alternatives. I hadn't thought about that before. Thank you for pointing that out. Did I repeat the question? I'm sorry. I said I'd do it, and then I'm screwing that up. Junichi? Yes, that's it. I remember you, right? OK. Junichi pointed out that, well, you'd also want to install the slave sim link. For instance, for x-term, if its man page had been translated. So what if it had been translated into 30 languages? Well, that command line, which was already pretty long. Whoops, it's right there. OK, that's long enough, right? Well, what if I had 30 translations? That would get absurdly long. Unfortunately, I think update alternatives is not granular enough to handle just calling it over and over again with different slave sim links. It would be worth learning. It would be worth finding that out. The alternative, I guess I can think of, instead of putting this into a for loop, you could do shell tricks, maybe x-args, maybe command substitution to make this happen. It's worth asking about on the mailing list if it's a problem you have to cope with. Alex? Yes? My successor is here. Just for the speaking, right? Not for leadership, right? OK. OK, I'm allowed to take one more question, and then we will proceed with Tolif's talk. OK. Yeah. If there are any more questions. Oh, yes? Under the sections, you didn't list bugs. Bugs is a part of the man page that I've had a lot of use for lately. The question was, the comment was, I didn't mention a bugs section. That wasn't quite an oversight. The SUS, single-unit specification, actually doesn't document bugs sections. In my opinion, those should be subsections of the description or, well, yeah, pretty much of the description. There is a macro. There's a request for subsections instead of .sh. It's .ss, and these are capital letters because they're part of the macro package instead of graph. I didn't actually cover that item in my talk either. I did prepare this talk in a hurry. I apologize for that. I might have had some time to think about it more carefully had I taken the time. So are the last slides showing the hell of your slides? No, because I haven't put them on the web yet. But we can put your slides on the web, and people can see the rest of the slides there. Yes. So thanks for trying to summarize a 90-minute workshop into a 45-minute slot talk. Thank you very much. Thanks for listening, guys.