eurobsdcon2014-mandoc-slides004075500017500001750000000000001241203143700170125ustar00ischwarzeischwarzeeurobsdcon2014-mandoc-slides/talk.roff010064400017500001750000000033341240704656200207130ustar00ischwarzeischwarze.\" .\" The following Copyright notice, license and disclaimer .\" applies to all files of this presentation except the images .\" and is not repeated in each individual file. .\" .\" Copyright (c) 2014 Ingo Schwarze .\" .\" Permission to use, copy, modify, and distribute this presentation for any .\" purpose with or without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" .\" THE PRESENTATION IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL .\" WARRANTIES WITH REGARD TO THIS PRESENTATION INCLUDING ALL IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE .\" AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL .\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA .\" OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR .\" PERFORMANCE OF THIS PRESENTATION. .\" .\" -------------------------------------------------------------------- .\" .\" These slides use the mm and gpresent groff macros. .\" For example, on OpenBSD, install these ports: .\" groff, gpresent, ghostscript. .\" For build instructions, see the Makefile. .\" .\" -------------------------------------------------------------------- .\" .so settings.roff .TITLE "Let's make manuals more useful!" .so header.roff .so macros.roff .so title.roff .so footer.roff .so 0/section.roff .so 1/section.roff .so 2/section.roff .so 3/section.roff .so Ex/1.roff .nr gpe_time_tsec 15*60+55*60 .so 4/section.roff .nr gpe_time_tsec 16*60+15*60 .so break.roff .so 5/section.roff .so 6/section.roff .so Ex/2.roff .nr gpe_time_tsec 17*60+15*60 .so 7/section.roff eurobsdcon2014-mandoc-slides/header.roff010064400017500001750000000022631240461426300212040ustar00ischwarzeischwarze.\" === gpresent header setup ========================================== .\" We don't want a header line for the title page, .\" so we have to start it before setting up headers. .\" --- define gpresent extension registers ---------------------------- .nr gpe_page_tot 1 .nr gpe_page_sec 0 .af gpe_page_sec I .nr gpe_time_tsec 14*60+17*60 .nr gpe_time_hour 14 .nr gpe_time_min 17 .af gpe_time_min 02 .nr gpe_time_sec 0 .af gpe_time_sec 02 . .\" --- macro to start a new section ----------------------------------- .de GPE_SECTION .ds gpe_title_sec \\$1 .nr gpe_page_sec 0 .. .\" --- macro to prepare a new page ------------------------------------ .de GPE_NEXT .ds gpe_next \\$1 .ds gpe_paper \\$2 .SK .. .\" --- gpresent page header callback ---------------------------------- .de HEADER .nr gpe_page_tot +1 .nr gpe_page_sec +1 .sp 0.5v .ds gpe_middle page \\n[gpe_page_tot]: \\*[gpe_title_sec] \\n[gpe_page_sec] .if !'\\*[gpe_paper]'' .as gpe_middle \ (\\*[gpe_paper]) .\"as gpe_middle \ (\\*[gpe_paper]) .tl 'Ingo Schwarze: Let\(aqs make manuals more useful!'\ \\*[gpe_middle]'\ EuroBSDCon 2014, September 26, Sofia' .sp -0.5v .\" horizontal line below the page header \l'\\n(.lu'\h'-\\n(.lu' .br .. eurobsdcon2014-mandoc-slides/Makefile010064400017500001750000000004641240725446400205450ustar00ischwarzeischwarzetalk.pdf: talk.ps ps2pdf talk.ps talk.ps: talk.pps presentps -l talk.pps > talk.ps talk.pps: talk.roff groff -mm -mpresent talk.roff > talk.pps clean: rm -f talk.ps talk.pps talk.pdf test: groff -mm -mpresent test.roff > test.pps presentps -l test.pps > test.ps ps2pdf test.ps .PHONY: clean test eurobsdcon2014-mandoc-slides/Ex004075500017500001750000000000001240633775100174015ustar00ischwarzeischwarzeeurobsdcon2014-mandoc-slides/Ex/work.roff010064400017500001750000000232021240504125500213020ustar00ischwarzeischwarze.H 2 "Recommended exercises" The following exercises are recommended for the following target audiences. Of course, all participants are free to choose any exercise they are interested in. See the table of contents at the very end of this document. .P The exercises marked "second phase" are easier to handle in the second working phase because the subject will only be explained .I after the first working phase. If you have a strong interest in some exercise marked "second phase" and feel able to handle it, there is nothing wrong with attempting it in the (longer) first working phase, though. .BVL 5n .LI "Software or documentation developers..." .BVL 5n .LI "... working on software lacking one or more manual pages:" first phase: .GETR mdoc_write .LI "... working on software having non-mdoc documentation:" first phase: .GETR mdoc_migrate .LI "... working on software having mdoc documentation:" first phase: .GETR check_basic .LI "... maintaining a portable software package:" first phase: .GETR makefile_tman .GETR configure_write .LE .LI "Porters and port maintainers:" first phase: .GETR check_basic .GETR check_bulk .br second phase: .GETR makewhatis_test .GETR integration_test .LI "Operating system developers and documentation maintainers:" first phase: .GETR check_bulk .br second phase: .GETR makewhatis_test .GETR integration_test .LI "System administrators:" second phase: .GETR integration_test .LI "End users:" second phase: .GETR makewhatis_test .LE . .H 2 "Using the mdoc(7) formatting language" .H 3 "Writing a manual from scratch" .SETR mdoc_write If there is a software, ideally not too complex and with a limited number of features, that you maintain or just care about and that doesn't have any manual page yet, start writing a manual page for it using the .Xr mdoc 7 language. .P Hints: .BL .LI Be careful to not get lost in details. .LI Start by setting up the preamble and .I all required section titles. .LI In each section, take rough notes which material will need to be covered in that section. Only after that, start filling in individual sections. .LI Pay particular attention to get the beginning of the DESCRIPTION concise and clear. It should clearly state the purpose of the software and not be wordy. .LI When drafting lists, first figure out which list entries will be needed, only then start filling them in. .LI If there is more material to cover than you can finish during the tutorial, don't fear leaving blanks in the middle. Try to work on as many different parts as possible and take advantage of the chance to ask questions that arise. .LI Consider submitting the result to the software maintainer for inclusion, possibly after finishing it at home if time is insufficient during the tutorial. .LE . .H 3 "Translating a manual to mdoc" .SETR mdoc_migrate If there is a software, ideally not too complex and with a limited number of features, that you maintain or just care about and that has a manual in a language different from .Xr mdoc 7 , start translating the manual to .Xr mdoc 7 . Working on this exercise is particularly useful if you have reason to believe that the maintainer might be willing to switch the format. .P Hints: .BL .LI Be sure to keep a copy of the original. .LI If there is more material to cover than you can finish during the tutorial, don't fear leaving blanks in the middle. Try to work on as many different parts as possible and take advantage of the chance to ask questions that arise. .LI If the original was a .Xr man 7 page, compare the output of .Xr mandoc 1 from your version with the output .Cm mandoc .Fl Omdoc produces from the original version. .LI Consider submitting the result to the software maintainer for inclusion, possibly after finishing it at home if time is insufficient during the tutorial. .LE . .bp .H 2 "Manual pages for portable software" .H 3 "Package autogenerated man and cat" .SETR makefile_tman Take a portable software package you maintain or care about that already has .Xr mdoc 7 manuals or where you consider converting the manuals to .Xr mdoc 7 . Design and implement .Xr make 1 targets in the distribution tarball build system to generate and package .Xr man 7 and cat (preformatted) versions of the existing .Xr mdoc 7 manuals. .P Caveat: .P The difficulty of this exercise, and the amount of work required, can vary greatly depending on the size and complexity of the software package and the build system used. For a large or complex package, familiarity with the build system is probably required. .P Hints: .BL .LI You must have a checked out copy of the source repository. This exercise cannot be solved starting from a mere release tarball. .LI If the .Xr mdoc 7 versions of the pages have not yet been written, don't waste your time on that, just write two or three ten-line stubs to get started. .LI Pay attention to not edit autogenerated files, like .Pa Makefile if there is also .Pa Makefile.in . .LI Try to use .Xr make 1 inference (suffix) transformation rules. Avoid writing one rule for each manual page if possible. .LI To test your changes, build and inspect a release tarball. .LE . .H 3 "Write configuration tests" .SETR configure_write Take a portable software package you maintain or care about that already has .Xr mdoc 7 manuals or where you consider converting the manuals to .Xr mdoc 7 . Design and implement configuration tests to decide whether to install mdoc, man, or cat manuals on the target system. .P Caveat: .P The difficulty of this exercise, and the amount of work required, can vary greatly depending on which build system is used and how it is used. You better have a at least a rough idea what you are doing and some experience with the build system in question, or at least with build systems in general, before attempting this exercise. .P Hints: .BL .LI If possible, check out a copy of the source repository of the software to work in. Depending on the build system used, merely having a release tarball may or may not be sufficient to do meaningful work on this exercise. .LI Pay attention to not edit autogenerated files, like .Pa ./configure in software using GNU .Xr autoconf 1 . .LI An easy test of your changes can probably be done in the checkout area by running the tool to regenerate autogenerated files, then running the configuration script and inspect what it detects. .LI The ultimate test would be to build a release tarball, than test from that. .LE . .H 2 "Quality control for existing manuals" .H 3 "Checking one or a few specific pages" .SETR check_basic Choose a small number of manual pages you maintain or care about. Run those check tools \(em .Xr mandoc 1 .Fl Tlint , .Xr mdoclint 1 , .Xr igor 1 , and maybe gmdiff \(em you have installed or can easily install on them. Prioritize your findings and take notes about those you consider relevant. If desired, prepare patches to improve the manuals. .P Ask somebody who is experienced with .Xr mdoc 7 to have a look at your patches, then send them upstream for inclusion. . .H 3 "Running bulk quality checks" .SETR check_bulk In a larger tree of manuals you maintain or care about, run .Nm mandoc .Fl Tlint .Fl Wfatal , solve any issues showing up, run .Nm mandoc .Fl Tlint .Fl Werror , and start working on the issues found. .P Hints: .BL .LI Don't be shy to use .Xr find 1 or scripting as required to quickly and efficiently get at the files you need. On the other hand, don't waste your time devising elaborate frameworks right now; this tutorial is about manuals, not about build systems! .LI Refrain from large-scale patching until you are really sure what you see are large-scale errors in your tree and cannot reasonably be solved in other ways, for example by improving .Xr mandoc 1 . For this exercise, communication is of particular importance, there .I are people around you can talk to! .LI If you arrive in a state where the are no more errors, you can proceed to look at warnings. .LE . .H 2 "Searching and displaying manual pages" .H 3 "Testing makewhatis and apropos" .SETR makewhatis_test Choose a manual tree you are maintaining or care about. Run .Xr makewhatis 8 on it. Try out various .Xr apropos 1 features and try to discover issues. Report any you find to me. .P Hints: .BL .LI For this exercise, having an up-to-date mandoc suite is more important than for most. Consider checking out from anoncvs@mdocml.bsd.lv:/cvs and building and installing from that before starting. On OpenBSD, it is better to build from .Pa /usr/src/usr.bin/mandoc instead. .LI To run .Xr makewhatis 8 on one specific tree only, you will need the .Ar dir argument. .LI If everythings appears to be working fine, try to refine your methods. For example, try the .Fl p , .Fl D , and .Fl DD options of .Xr makewhatis 8 and try to understand the output. .LI Probably, most of the output will be false positives, but you may also find some real bugs in the manuals in this way that can be worth patching. .LI If you are comfortable with SQL, run the .Xr sqlite3 1 command line client directly on the database generated by .Xr makewhatis 8 and look for anything that seems questionable. .LE . .H 3 "Checking manual locations and formats" .SETR integration_test On your favourite operating system, figure out all locations where manuals are installed and identify those that .Xr man 1 searches by default. Figure out all formats of installed manual pages (formatted/unformatted, source language, compression, whatever). Check that .Xr makewhatis 8 and .Xr apropos 1 work for all locations and all formats. Report any issues you find to me. .P Hints: .BL .LI For this exercise, having an up-to-date mandoc suite is more important than for most. Consider checking out from anoncvs@mdocml.bsd.lv:/cvs and building and installing from that before starting. On OpenBSD, it is better to build from .Pa /usr/src/usr.bin/mandoc instead. .LE eurobsdcon2014-mandoc-slides/Ex/1.roff010064400017500001750000000001551240640016700204640ustar00ischwarzeischwarze.GPE_SECTION EXERCISES .so Ex/intro.roff .GPE_NEXT "Which exercises are proposed?" "8.0:40" .so Ex/list.roff eurobsdcon2014-mandoc-slides/Ex/intro.roff010064400017500001750000000015211240727057400214650ustar00ischwarzeischwarze.GPE_NEXT "Let's get our hands dirty..." "8:40" .TITLE "Exercises: general remarks" .AL .LI .B Choose what interests you, you cannot do them all; this phase: 1-3 tasks. .LI Do not waste time reading instructions for exercises you won't work on. .LI Feel free to work alone or with one or two partners at your choice. .LI .B Communicate , don't be shy to interrupt others for asking questions. .LI .sp -1.5v .MULB 7c 1n 12c .sp 0.5v \fBAvoid\fP time-consuming repetitive work during the tutorial. .sp For example, don't toil on a long of list options. .sp Just write down the first two or three. .sp Then move on to the next section. .MULN .PSPIC Images/PhilDavisSquirrel.eps .ce .GPE_SM "Squirrel digging \(co 2010 Phil Davis @flickr (CC)" .MULE .LI .B Present results .I "if you want to" (1-3 minutes, tell me while working). .LE .GPE_TIME 110 NEW eurobsdcon2014-mandoc-slides/Ex/list.roff010064400017500001750000000017441240640357400213110ustar00ischwarzeischwarze.TITLE "Recommended exercises" Of course, all participants are free to choose any exercise they are interested in. .BVL 5n .LI "Software or documentation developers..." .BVL 5n .LI "... working on software lacking one or more manual pages:" 8.1.1: (***) \fBWriting\fP a manual from scratch .LI "... working on software having non-mdoc documentation:" 8.1.2: (**) \fBTranslating\fP a manual to mdoc .LI "... working on software having mdoc documentation:" 8.3.1: (*) \fBChecking\fP one or a few specific pages .LI "... maintaining a portable software package:" 8.2.1: (****) \fBPackaging\fP autogenerated man and cat .br 8.2.2: (*****) Writing \fBconfiguration tests\fP .LE .LI "Operating system developers and port maintainers:" 8.3.2: (***) Running \fBbulk\fP quality checks .br or 8.3.1 above or 8.4.* below .LI "System administrators:" 8.4.2: (*** - ****) Checking manual \fBlocations and formats\fP .LI "End users:" 8.4.1: (* - ***) Testing makewhatis and \fBapropos\fP .LE .GPE_TIME 160 NEW eurobsdcon2014-mandoc-slides/Ex/2.roff010064400017500001750000000001511240641122500204560ustar00ischwarzeischwarze.GPE_SECTION EXERCISES .nr gpe_page_sec 2 .GPE_NEXT "Let's do some more work!" "8.0:40" .so Ex/list.roff eurobsdcon2014-mandoc-slides/settings.roff010064400017500001750000000004231241202765600216130ustar00ischwarzeischwarze.\" --- global mm configuration settings ------------------------------- .nr Pi 3 .\" --- global gpresent configuration settings ------------------------- .DEFCOLOR Kea1 0 0.8 0.48 .DEFCOLOR Kea2 0 0.5 0.3 .TITLECOLOR Kea1 .SUBTITLEFORMAT C .SUBTITLECOLOR Kea2 .FOOTERSIZE 2 eurobsdcon2014-mandoc-slides/macros.roff010064400017500001750000000016501240012514400212260ustar00ischwarzeischwarze.\" === define some gpresent extension macros ========================== .\" --- two-column mode (for images) ----------------------------------- .\" 1st arg: width of first column .\" 2nd arg: move second column up by this amout (default 0.5v) .\" switch column with normal .MULN, end with normal .MULE .de GPE_MULB .nr gpe_colwr \\n(.l-\\$1-1n .ie \\n[.$]>1 .ds gpe_vsp \\$2 .el .ds gpe_vsp 0.5v .sp -\\*[gpe_vsp] .MULB \\$1 1n \\n[gpe_colwr]u .sp \\*[gpe_vsp] .. .\" --- emphasis ------------------------------------------------------- .\" arg: text .de GPE_EM .COLOR red \\$1 .COLOR P .. .\" --- small text ----------------------------------------------------- .\" arg: text .de GPE_SM .S -4 \\$1 .S P .. .\" --- small text with one emphasised word ---------------------------- .\" 1st arg: text before emphasis .\" 2nd arg: emphasised text .\" 3rd arg: text after emphasis .de GPE_SMEM .ce 3 .GPE_SM "\\$1 \m[red]\\$2\m[] \\$3" .. eurobsdcon2014-mandoc-slides/title.roff010064400017500001750000000017711240732641500211020ustar00ischwarzeischwarze.\" --- title page ----------------------------------------------------- .\" The main title line has already been printed. .SUBTITLE "Tutorial on software documentation" .SUBTITLE "EuroBSDCon 2014, September 26, Sofia" .SUBTITLE "Ingo Schwarze " .sp .ce .GPE_SM "using some material from:" .sp .MULB 8c 1n 4c 1n 9c .ce 4 Training a foal to .br replace a venerable workhorse: .br mandoc in OpenBSD .br BSDCan 2011 .MULN .MULN .ce 4 Enhancing the modern toolbox for .br the classic documentation formats: .br new trends in mandoc .br BSDCan 2014 .MULE .MULB 7c 1n 7c 1n 7c .PSPIC Images/TomkoFoal.eps .MULN .PSPIC Images/BSDSofiaForWeb.eps 4c .MULN .PSPIC Images/BrentBarrettKea.eps .MULE .MULB 7c 1n 7c 1n 7c .ce 2 .GPE_SM "Csik\('o \(em Foal" .GPE_SM "\(co 2010 Adam Tomk\('o @flickr (CC)" .MULN .ce 2 .GPE_SM "\f[CYR]Sofi\(ya\fP BSD Mascot" .GPE_SM "\(co 2014 \f[CYR]Alica Dimitrova\fP" .MULN .ce 2 .GPE_SM "Kea juvenile (Nestor notabilis)" .GPE_SM "\(co 2007 Brent Barrett @flickr (CC)" .MULE eurobsdcon2014-mandoc-slides/footer.roff010064400017500001750000000014351240640454100212500ustar00ischwarzeischwarze.\" --- gpresent footer setup ------------------------------------------ .\" We dont want a footer line for the title page, .\" so we have to set it up after completing the title page. .GPE_SECTION INTRO .GPE_NEXT "" "0.1.2:1" .\" --- macros to start a new page ------------------------------------- .\" arg: time for this page in seconds .de GPE_TIME .nr gpe_time_tsec +\\$1 .nr gpe_time_hour \\n[gpe_time_tsec]/3600 .nr gpe_time_min \\n[gpe_time_tsec]%3600/60 .nr gpe_time_sec \\n[gpe_time_tsec]%60 .ds gpe_source \\$2 .. .\" --- gpresent page footer callback ---------------------------------- .de FOOTER .ps 18 .vs 20 .sp -2v \l'\\n(.lu'\h'-\\n(.lu' .br .tl '\s-6\\n[gpe_time_hour]:\\n[gpe_time_min]:\s-2\\n[gpe_time_sec]\ \\*[gpe_source]\s+8''\\m[Kea2]\\*[gpe_next]\ \ \(->\\m[]' .ps .vs .. eurobsdcon2014-mandoc-slides/0004075500017500001750000000000001240460601700171545ustar00ischwarzeischwarzeeurobsdcon2014-mandoc-slides/0/section.roff010064400017500001750000000004141240460363500215540ustar00ischwarzeischwarze.so 0/goals.roff .so 0/man_intro.roff .so 0/formats_intro.roff .so 0/roff.roff .so 0/roff_sample.roff .so 0/roff_plus.roff .so 0/man.roff .so 0/mdoc.roff .so 0/mdoc_sample.roff .so 0/formats_plus.roff .so 0/mandoc_plus.roff .so 0/contents.roff .so 0/participants.roff eurobsdcon2014-mandoc-slides/0/formats_intro.roff010064400017500001750000000013431240740030200227650ustar00ischwarzeischwarze.GPE_NEXT "What do authors use?" "0.3:3" .GPE_SMEM Let's make "manuals more useful - the author's perspective." .TITLE "Let's write manuals!" So we need a markup language that is: .BL .LI easy to write .LI easy to diff(1) .LI easy to read and change .LI easily supports semantic markup .LI readily produces various output formats .LI easily supports portability .LE .sp One simple, versatile language: \fBmdoc(7)\fP \(em with a long tradition: .BL .LI Based on the roff(7) language (1964). .LI Successor of the man(7) language (1979). .LI Designed for 4.4BSD at Berkeley (1990). .LI Implemented by mandoc(1) (2008) and groff(1) (1989). .LI .GPE_EM "Used by default in OpenBSD, NetBSD, FreeBSD, DragonFly and illumos." .LE .GPE_TIME 60 NEW eurobsdcon2014-mandoc-slides/0/formats_plus.roff010064400017500001750000000011771240640525200226320ustar00ischwarzeischwarze.GPE_NEXT "Classic documentation formats (summary)" "0.8:5" .TITLE "Classic documentation formats (summary)" .BL .LI The roff(7) input syntax, .LI the mdoc(7) semantic markup, .LI and the man(1) presentation format .LE .sp 0.5v .ce .GPE_EM "have proven timeless by their simplicity and efficiency:" .sp -0.5v .BL .LI Nobody has come up with a better basic concept yet, .LI even though many have tried, .LI and regarding the formats, there is indeed little one could wish. .LE .PSPIC Images/AndrewRockWren.eps 10c .ce .GPE_SM "Rock Wren / Hurupounamu (Xenicus gilviventris)\ \(co 2006 57Andrew@flickr (CC)" .GPE_TIME 30 "BSDCan 2014 p. 9" eurobsdcon2014-mandoc-slides/0/man.roff010064400017500001750000000017661240640520200206660ustar00ischwarzeischwarze.GPE_NEXT "Application to software manuals?" "0.6:4" .GPE_SMEM "Enhancing the modern toolbox for the classic"\ documentation formats: .TITLE "Origin of the basic manual structure" .GPE_MULB 4i .GPE_EM "AT&T Version 1 UNIX manual" .P formatted with roff .P by Ken Thompson .br and Dennis M. Ritchie, .br Bell Labs, 1971 .P written in assembler .br for UNIX on the DEC PDP-11 .P .GPE_SM "inspired by the CTSS manuals" .P Section headers in use since v1: .br NAME, SYNOPSIS, DESCRIPTION, FILES, SEE ALSO, DIAGNOSTICS, BUGS .MULN .PSPIC Images/BellPDP11.eps (u;\n(.l-\n(.i)u .ce 2 .GPE_SM "Ritchie, Thompson, PDP-11 \(co 1971 Bell Labs" .GPE_SM "Reprinted with permission of Alcatel-Lucent USA Inc." .MULE .P Precursors to man(7) and mdoc(7) macros, used in v4\(env6 (1973-1975): .P \f(CW.th\fP (\(-> .TH/.Dt)\ \ \ \f(CW.sh\fP (\(-> .SH/.Sh)\ \ \ \ \f(CW.bd\fP (\(-> .B/.Sy)\ \ \ \f(CW.it\fP (\(-> .I/.Em) .P .GPE_EM "The man(7) language first appeared in Version 7 AT&T UNIX (1979)." .GPE_TIME 60 "BSDCan 2014 p. 6" eurobsdcon2014-mandoc-slides/0/man_intro.roff010064400017500001750000000016231240737656700221170ustar00ischwarzeischwarze.GPE_NEXT "How does the user experience manuals?" "0.2:2" .GPE_SMEM "Let's make" manuals "more useful - the user's perspective." .TITLE "Let's read a manual!" One comprehensive tool: \fBman(1)\fP, the manual viewer .AL .LI Find one or more manuals in the file system. .LI Transparently call a formatter on them, where required. .LI Display the formatted text, typically in a pager. .LE .sp Progress during the last few months: .BL .LI The mandoc toolbox now provides one single tool for all this. .LI Unified, simple .GPE_EM "user interface" available since August 26, 2014. .LI The traditional way required multiple programs: apropos for searching, man for steering, nroff or mandoc for formatting, ... .LI Semantic .GPE_EM searching in production since April 14, 2014. .LI New man.cgi(8) is .GPE_EM online on www.openbsd.org since July 12, 2014. .LE .sp More details on .GPE_EM "all this" later! .GPE_TIME 90 NEW eurobsdcon2014-mandoc-slides/0/mandoc_plus.roff010064400017500001750000000020271240740120600224070ustar00ischwarzeischwarze.GPE_NEXT "So we need modern tools for all this!" "0.9:5" .GPE_SMEM Enhancing "the modern toolbox"\ "for the classic documentation formats:" .TITLE "Advantages of mandoc(1)" .BL .LI Functional \(em all in one binary: .BL .LI Searching by filename, page name, word, substring, regular expression, semantic keys .LI mdoc(7), man(7), tbl(7) and some eqn(7) and roff(7) input .LI ASCII, UTF-8, HTML, XHTML, PostScript, PDF output .LI mdoc(7) to man(7) conversion .LI includes mandoc(1), man(1), apropos(1), whatis(1), makewhatis(8) .LE .LI Free \(em ISC/BSD-licensed, no GPL code. .LI Lightweight \(em ANSI C, POSIX, no C++ code. .LI Portable \(em includes compat_*.c files for missing functions on older systems. .LI Small \(em source tarball (uncompressed) is 8% of groff, executable binary 50%. .LI Fast \(em for mdoc(7), typically 5 times faster than groff, typically about a hundred times faster than an AsciiDoc/DocBook toolchain. .LE .sp .ce .GPE_EM "Basic functionality already presented during BSDCan 2011." .GPE_TIME 90 "BSDCan 2014 p. 10" eurobsdcon2014-mandoc-slides/0/mdoc.roff010064400017500001750000000021751240640521700210360ustar00ischwarzeischwarze.GPE_NEXT "Was there any progress during the last 35 years?" "0.7:5" .GPE_SMEM "Enhancing the" modern\ "toolbox for the \m[red]classic\m[] documentation formats: .TITLE "Origin of semantic markup in manuals" .GPE_MULB 18c 2v .BL .LI The mdoc(7) semantic markup macro language. .LI First in 4.3BSD-Reno by Cynthia Livingston, USENIX, 1990. .LI Formatted with Brian Kernighan's device independent troff, .LI written in K&R C, running on BSD UNIX on DEC VAX. .LE .SUBTITLE "Advantages of the mdoc(7) language" .MULN .PSPIC Images/BSDBeastie.eps .GPE_SM "4.2BSD Beastie" .MULE .BL .LI Considerable expressive power for semantic markup \(em .br while man(7) is a presentation level language only. .LI Works in practice as a standalone language \(em .br while man(7) regularly requires resorting to low-level roff features. .LI Consequently, more uniform appearance, easier to read and write than man(7). .LI Portability is no longer an issue: for legacy systems still not having mdoc(7), mandoc(1) can be used to convert to man(7) \(em see this talk. .LI .GPE_EM "Facilitates semantic searching \(em see this talk." .LE .GPE_TIME 100 "BSDCan 2014 p. 7" eurobsdcon2014-mandoc-slides/0/mdoc_sample.roff010064400017500001750000000016171240477176200224100ustar00ischwarzeischwarze.GPE_NEXT "How does mdoc(7) code look like?" .TITLE "Sample mdoc(7) source code" .VERBON 1 14 .Dd $Mdocdate: March 31 2014 $ .Dt MDOC 7 .Os .Sh NAME .Nm mdoc .Nd semantic markup language for formatting manual pages .Sh DESCRIPTION The .Nm mdoc language supports authoring of manual pages for the .Xr man 1 utility by allowing semantic annotations of words, phrases, page sections and complete manual pages. Such annotations are used by formatting tools to achieve a uniform presentation across all manuals written in .Nm , and to support hyperlinking if supported by the output medium. .Pp This reference document describes the structure of manual pages and the syntax and usage of the .Nm language. The reference implementation of a parsing and formatting tool is .Xr mandoc 1 ; the .Sx COMPATIBILITY section describes compatibility with other implementations. .VERBOFF .GPE_TIME 30 eurobsdcon2014-mandoc-slides/0/roff.roff010064400017500001750000000015351240640502600210450ustar00ischwarzeischwarze.GPE_NEXT "How do the markup languages look like?" "0.4:3" .GPE_SMEM "Enhancing the modern toolbox for the" classic\ "documentation formats:" .TITLE "Classic roff markup syntax" .ce Classic = literally half a century of history! .sp 1.5v .GPE_MULB 10c The concept of text and macro lines: .P .GPE_EM "RUNOFF (later became \(lqroff\(rq)" .P by Jerome H. Saltzer, MIT, 1964 .P in MAD for CTSS on the IBM 7094 .P .GPE_SM "inspired by Memo, Modify, and Ditto" .br .GPE_SM "by Lowry/Corbato/Steinberg 1963." .P Requests still in use today: .VERBON 2 16 \&.ad .ce .fi .in .ll .nf \&.br .sp .VERBOFF .MULN .PSPIC Images/ColumbiaIBM7094.eps .GPE_SM "IBM 7094 \(co 1965 Columbia Univ. Archives (Courtesy)" .MULE .sp 1.5v Macro lines contain a period (\(oq.\(cq), a macro name, and optional arguments. .P All other lines are text lines. .GPE_TIME 100 "BSDCan 2014 p. 3" eurobsdcon2014-mandoc-slides/0/roff_plus.roff010064400017500001750000000012631240740046200221060ustar00ischwarzeischwarze.GPE_NEXT "OK, try again:\ \ Why do we still use that syntax 50 years later?" "0.5:4" \& .TITLE "Advantages of the roff macro syntax" .S +2 .BL .LI Can easily be hand-edited with minimal typing overhead. .LI Looks unobtrusive, does not muddle the actual text. .LI Harmonizes very well with diff(1). .LI Allows high quality output in multiple output formats, .br in particular for terminal output and typesetting. .LI Works with simple, fast, portable, readily available tools. .LI Does not need any heavyweight or cumbersome toolchains, .br in particular, does not require XML. .LE .sp 2v .ce 2 \&... or say it in one word: .sp 2v .S +4 .GPE_EM "KISS!" .S -6 .GPE_TIME 80 "BSDCan 2014 p. 5" eurobsdcon2014-mandoc-slides/0/roff_sample.roff010064400017500001750000000014141240477155400224140ustar00ischwarzeischwarze.GPE_NEXT "Why do we still use that syntax 50 years later?" .TITLE "Sample roff(7) source code" .VERBON 1 14 .TITLE "Advantages of the roff macro syntax" .S +2 .BL .LI Can easily be hand-edited with minimal typing overhead. .LI Looks unobtrusive, does not muddle the actual text. .LI Harmonizes very well with diff(1). .LI Allows high quality output in multiple output formats, .br in particular for terminal output and typesetting. .LI Works with simple, fast, portable, readily available tools. .LI Does not need any heavyweight or cumbersome toolchains, .br in particular, does not require XML. .LE .sp 2v .ce 2 \&... or to say it in one word: .sp 2v .S +4 .GPE_EM "KISS!" .S -6 .GPE_NEXT 50 "Application to software manuals?" .VERBOFF .GPE_TIME 40 eurobsdcon2014-mandoc-slides/0/goals.roff010064400017500001750000000013001240640245600212100ustar00ischwarzeischwarze.GPE_SMEM "Let's make manuals more" useful! "" .TITLE "Requirements for good documentation" .BL .LI correct .LI complete .LI concise .LI easy to find and access, all in one local place .LI not just plain text: function of words must be marked up for display and search .LI easy to read: in particular, uniform display markup and style .LI easy to write: in particular, one simple, standard input language .LE .sp 1.5v The formatted documentation must seem simple to end users. .P The language to write documentation must seem simple to programmers. .sp 1.5v .ce 3 Remember: .GPE_EM "Without documentation, code is unusable," .GPE_EM "and bad documentation is about as bad as bad code." .GPE_TIME 100 NEW eurobsdcon2014-mandoc-slides/0/contents.roff010064400017500001750000000015651240640546100217540ustar00ischwarzeischwarze.GPE_NEXT "What are we going to do?" "45" .TITLE "Contents of this tutorial" .GPE_MULB 12c .VL \n(Pi .LI 0. Introduction .LI 1. Using the mdoc(7) formatting language .LI 2. Manual pages for portable software .LI 3. Quality control for existing manuals .LI * First hands-on working phase (30 min.) .LI 4. Searching and displaying manual pages .LI * Coffee break (15 min.) .LI 5. Integrating mandoc as a base system .br documentation formatter .LI 6. Integrating mandoc as a ports .br documentation formatter .LI * Second hands-on working phase (15 min.) .LI 7. Status and next steps .LE .MULN .PSPIC Images/NZDOCKakapoChicks.eps .ce 2 .GPE_SM "Kakapo chicks (Strigops habroptilus)" .GPE_SM "\(co 2009 NZ DOC @flickr (CC)" .MULE .sp .ce 2 The tutorial will officially end at about 17:30. .br We can continue work & discussions in a smaller group if any of you want to. .GPE_TIME 180 NEW eurobsdcon2014-mandoc-slides/0/participants.roff010064400017500001750000000011451240740141500226060ustar00ischwarzeischwarze.GPE_NEXT "Who are we?" \& .TITLE "Short introduction of ourselves" .sp Four short sentences per participant: .BL .LI Name .LI Main role (application programmer, technical writer, operating system developer, system administrator, BSD user, ... ?) .LI Main project affiliation .LI Most important goal for this tutorial .LE .sp 2v Let me start: .BL .LI Ingo Schwarze .LI Current mandoc project lead at mdocml.bsd.lv .LI OpenBSD operating system developer (userland) .LI Show you the current state of the art in BSD system documentation .br and try to help with any questions you might have... .LE .GPE_TIME 720 NEW eurobsdcon2014-mandoc-slides/1004075500017500001750000000000001240501305500171505ustar00ischwarzeischwarzeeurobsdcon2014-mandoc-slides/1/section.roff010064400017500001750000000006541241202777400215660ustar00ischwarzeischwarze.\" How to get started using the mdoc(7) formatting language for writing .\" new software manuals, how to do so without spending too much time .\" learning the language, and which resources to use while working .\" on mdoc(7) manuals. .\" .GPE_SECTION MDOC .so 1/concepts.roff .so 1/prologue.roff .so 1/synopsis_utility1.roff .so 1/synopsis_utility2.roff .so 1/synopsis_function.roff .so 1/description.roff .so 1/resources.roff eurobsdcon2014-mandoc-slides/1/prologue.roff010064400017500001750000000020021240735722600217450ustar00ischwarzeischwarze.GPE_NEXT "How does the prologue look like?" "1.1.1:6" .TITLE "The mdoc(7) prologue" .sp -0.5v .ce .GPE_EM "Macro lines only, no text lines!" .sp 0.5v Always use the following macros in the following order: .BL \n(Pi 1 .LI \fBDd\fP Document date: \fIMonth day, year\fP .LI \fBDt\fP Document title: \fINAME\fP (ALL CAPS) and \fIsection\fP number (see mdoc(7)). .LI \fBOs\fP Optional operating system name: Just leave it blank. .LI \fBSh\fP Section header: Argument must be \fBNAME\fP. .LI \fBNm\fP Page name: Here use its proper case. .LI \fBNd\fP One-line description: No quoting is needed. .LE .sp 0.5v .ce .GPE_EM "If your prologue has \fIsix\fP lines, it's probably complete." .GPE_MULB 13c 1v For example: .sp 0.5v .VERBON 22 14 \&.Dd July 16, 2013 \&.Dt CAT 1 \&.Os \&.Sh NAME \&.Nm cat \&.Nd concatenate and print files .VERBOFF .sp 0.5v .rj 2 .GPE_SM "\f[CYR]Centralna mineralna ban\(ya, Sofi\(ya\fP" .GPE_SM "\(co 2010 \f[CYR]Mihal Orela\fP @flickr (CC)" .MULN .PSPIC Images/MihalOrelaBath.eps .MULE .GPE_TIME 110 NEW eurobsdcon2014-mandoc-slides/1/concepts.roff010064400017500001750000000014431240732630300217270ustar00ischwarzeischwarze.GPE_NEXT "Let's write manuals..." "1.1:6" .GPE_SMEM Let's make "manuals more useful!" .TITLE "Basic concepts you need right away" .GPE_MULB 12c .BL .LI Macro lines (for markup) vs. text lines. .VERBON 18 \&.Sh HISTORY An \&.Fn fopen function first appeared in \&.At v1 . .VERBOFF .LI Macro arguments are separated by blanks. .LI Quoting allows blanks in arguments. .VERBON 22 \&.Ft "FILE *" \&.Fo fopen \&.Fa "const char *path" \&.Fa "const char *mode" \&.Fc .VERBOFF .LE .MULN .PSPIC Images/StGeorgeRotunda.eps .ce 2 .GPE_SM "\f[CYR]Rotonda Sveti Georgi, Sofi\(ya\fP" .GPE_SM "\(co 2006 \f[CYR]Preslav\fP @wikimedia (PD)" .MULE .sp For more details about roff syntax, see the roff(7) manual. .sp .BL .LI Every page starts with a prologue. .LI Content is organized into sections. .LE .GPE_TIME 110 NEW eurobsdcon2014-mandoc-slides/1/synopsis_function.roff010064400017500001750000000016521240732361300237100ustar00ischwarzeischwarze.GPE_NEXT "What about functions?" "1.1.2:7" .TITLE "SYNOPSIS for a function" .sp -0.5v .GPE_MULB 8c 0v Required macros: .BL 5n 1 .LI \fBIn\fP include file .LI \fBFt\fP function type .LI \fBFo\fP open function decl. .LI \fBFa\fP function argument .LI \fBFc\fP close function decl. .LE .P Typical example: .VERBON 22 14 \&.Sh SYNOPSIS \&.In unistd.h \&.Ft ssize_t \&.Fo read \&.Fa "int d" \&.Fa "void *buf" \&.Fa "size_t nbytes" \&.Fc .VERBOFF Formatted output: .VERBON 22 14 \fBSYNOPSIS\fP \fB#include \fP \fIssize_t\fP \fBread\fP(\fIint d\fP, \fIvoid *buf\fP, \fIsize_t nbytes\fP); .VERBOFF .MULN .sp .PSPIC Images/TodorBozhinovVitosha.eps .ce 2 .GPE_SM "\f[CYR]Hotel N\(yu Otani 98m i Vito\(sha 2290m\fP" .GPE_SM "\(co 2006 \f[CYR]Todor Bo\(zhinov\fP @flickr (CC)" .MULE The .B Fo macro is a .I "block macro" starting a scope .br that requires .I explicit closure by the .B Fc companion macro. .GPE_TIME 70 NEW eurobsdcon2014-mandoc-slides/1/synopsis_utility2.roff010064400017500001750000000016511240736254500236560ustar00ischwarzeischwarze.GPE_NEXT "What's new in this example?" "1.1.2:7" .TITLE "SYNOPSIS for a utility (2)" .GPE_MULB 11c .sp Typical example: .VERBON 22 14 \&.Sh SYNOPSIS \&.Nm cat \&.Op Fl benstuv \&.Op Ar .VERBOFF .sp 0.5v Formatted output: .VERBON 22 14 \fBSYNOPSIS\fP \fBcat\fP [\fB\-benstuv\fP] [\fIfile ...\fP] .VERBOFF .MULN .PSPIC Images/NationalPalaceOfCulture.eps .ce 2 .GPE_SM "\f[CYR]Nacionalen dvorec na kulturata, Sofi\(ya\fP" .GPE_SM "\(co 2012 Bin in Garten @wikimedia (CC)" .MULE .sp -1v Important features: .BL .LI Most macros can take other macros as arguments. .LI The .I called macros don't have a dot, like .B Fl and .B Ar above. .LI The .B Op macro is an example of an .I enclosure macro, .br a special case of a .I block macro, .br having a .I scope that can contain macros and text. .LI For .B Op , the scope extends to the end of the input line. .LI A few macros have default arguments, like .B Ar above. .LE .GPE_TIME 110 NEW eurobsdcon2014-mandoc-slides/1/synopsis_utility1.roff010064400017500001750000000016011240736061200236410ustar00ischwarzeischwarze.GPE_NEXT "What is the first section after NAME?" "1.1.2:6" .TITLE "SYNOPSIS for a utility (1)" For utilities and functions, the first section after NAME is always SYNOPSIS. .BL .LI Only document syntax, not semantics. .LI No free text! .LI Formatting is fully automatic. .LE .P Required macros: .BL 5n 1 .LI \fBNm\fP Utility name. Usually the same you used in the NAME section. .LI \fBOp\fP Optional syntax element. .LI \fBFl\fP Command line options (flags). .LI \fBAr\fP Command line arguments. .LE .GPE_MULB 8c 0v .sp Typical example: .VERBON 22 14 \&.Sh SYNOPSIS \&.Nm cat \&.Op Fl benstuv \&.Op Ar .VERBOFF Formatted output: .VERBON 6 14 \fBSYNOPSIS\fP \fBcat\fP [\fB\-benstuv\fP] [\fIfile ...\fP] .VERBOFF .MULN .PSPIC Images/PanyGoffUniversity.eps .ce 2 .GPE_SM "\f[CYR]Sofijski universitet\fP" .GPE_SM "\(co 2011 \f[CYR]Plamen Agov\fP studiolemontree.com (CC)" .MULE .GPE_TIME 80 NEW eurobsdcon2014-mandoc-slides/1/description.roff010064400017500001750000000013061240640325600224340ustar00ischwarzeischwarze.GPE_NEXT "What about semantics?" "1.1.3:7" .TITLE "DESCRIPTION" .BL .LI Every manual has a DESCRIPTION section. .LI First explain the purpose of the utility or function. .LI Then describe the syntax and semantics of all features. .LI Be complete, but concise. .LI If it gets very long, it can be split into multiple sections. .LE .P Remaining sections have conventional names and a conventional order: .BL .LI RETURN VALUES (functions only) .LI ENVIRONMENT .LI FILES .LI EXIT STATUS (utilities only) .LI EXAMPLES .LI DIAGNOSTICS (utilities and drivers) .LI ERRORS (functions only) .LI SEE ALSO, STANDARDS, HISTORY, AUTHORS, CAVEATS, BUGS. .LE .P See the mdoc(7) manual for more information. .GPE_TIME 140 NEW eurobsdcon2014-mandoc-slides/1/resources.roff010064400017500001750000000020531240640327200221210ustar00ischwarzeischwarze.GPE_NEXT "Where can we get more information?" "1.2:7" .TITLE "Help on mdoc(7)" What was discussed so far should be sufficient to get started. .br You can look up all the rest when you need it... .BL .LI The mdoc(7) manual is the most important resource. .BL .LI which sections? \(em MANUAL STRUCTURE section .LI which macros? \(em MACRO OVERVIEW section .LI usage of a macro? \(em MACRO REFERENCE section .LE .LI Look at the manuals in the OpenBSD base system for examples. .br This is particularly helpful to find standard wordings and customary choices of macro arguments. For example, many pages contain this: .nr Verbin 10n .VERBON 22 The options are as follows: \&.Bl -tag -width Ds \&.It Fl a .VERBOFF .nr Verbin 5n .LI .B "mandoc -Tlint" catches most syntax errors and provides some hints on style. .LI The groff_mdoc(7) manual sometimes helps to resolve ambiguities. .LI Kristaps has written a full tutorial: http://manpages.bsd.lv/ .LI Ask for help on .br and provide suggestions to improve the mdoc(7) manual. .LE .GPE_TIME 280 NEW eurobsdcon2014-mandoc-slides/break.roff010064400017500001750000000003641240705052400210350ustar00ischwarzeischwarze.GPE_NEXT "Coffee break..." \& .TITLE "Coffee break" .GPE_TIME 900 .ce .GPE_EM "until \\n[gpe_time_hour]:\\n[gpe_time_min]" .PSPIC Images/MarkRobinsonQuantocks.eps .ce .GPE_SM "A Youngster on the Quantocks \(co 2009 Mark Robinson @flickr (CC)" eurobsdcon2014-mandoc-slides/2004075500017500001750000000000001241203066600171565ustar00ischwarzeischwarzeeurobsdcon2014-mandoc-slides/2/section.roff010064400017500001750000000003561241203022600215500ustar00ischwarzeischwarze.\" How to make sure that mdoc(7)-based documentation in a portable .\" software distribution is portable, using the mandoc(1) -Tman output .\" mode and the ./configure mechanism. .\" .GPE_SECTION \-Tman .so 2/choice.roff .so 2/sudo.roff eurobsdcon2014-mandoc-slides/2/choice.roff010064400017500001750000000016771240640562100213550ustar00ischwarzeischwarze.GPE_NEXT "Can we use this for portable software?" "2.1:11" .TITLE "Manual pages for portable software" .SUBTITLE "The problem" .BL .LI Consider portable software packages like sudo(8), OpenSSH, OpenSMTPd, ... .LI Which markup language should be chosen for the manual pages? .LI Use mdoc(7) and some legacy systems lose that still don't have mdoc(7) after it has been freely available for more than 20 years (hello, Solaris). .LI Use man(7) and everybody loses \(em that would be a very bad idea indeed. .LE .SUBTITLE "mandoc(1) to the rescue!" .BL .LI .GPE_EM "Write the manual pages using mdoc(7)." .LI Use mandoc -Tman to convert them to man(7) format. Fully operational since November 19, 2012. .LI Include both the mdoc(7) and man(7) versions into distribution tarballs. .LI Let \f(CW./configure\fP decide: .LI On systems supporting mdoc(7), install the mdoc(7) versions. .LI Otherwise, install the man(7) versions. .LE .GPE_TIME 120 "BSDCan 2014 p. 33" eurobsdcon2014-mandoc-slides/2/sudo.roff010064400017500001750000000015101240640563600210650ustar00ischwarzeischwarze.GPE_NEXT "Let's look at an example" "2.2:11" .TITLE "Case study: the sudo(8) manuals" .SUBTITLE "Build system for the distribution tarball" .GPE_MULB 17c 1.5v Simplified code from the Makefile: .sp 0.5v .VERBON 6 16 sudo.man: sudo.mdoc mandoc -Tman sudo.mdoc > sudo.man sudo.cat: sudo.mdoc mandoc sudo.mdoc > sudo.cat .VERBOFF .MULN .PSPIC Images/sudo.eps .MULE .SUBTITLE "Installation system" .BL .LI If \f(CW./configure\fP finds mandoc(1), install the *.mdoc pages .LI If \f(CW./configure\fP does not find nroff(1), install the *.cat pages .LI If \f(CW./configure\fP successfully tests \f(CWnroff -mdoc\fP, install the *.mdoc pages .LI Otherwise, install the *.man pages. .LI To override this autodetection logic, provide \f(CW--with-mdoc\fP or \f(CW--with-man\fP options to \f(CW./configure\fP. .LE .GPE_TIME 180 "BSDCan 2014 p. 34" eurobsdcon2014-mandoc-slides/3004075500017500001750000000000001240503623700171615ustar00ischwarzeischwarzeeurobsdcon2014-mandoc-slides/3/section.roff010064400017500001750000000004361241203027000215470ustar00ischwarzeischwarze.\" How to support quality control of existing manuals .\" using mandoc(1) -Tlint and other tools. .\" .GPE_SECTION "QA" .so 3/goals.roff .so 3/design.roff .so 3/fatal.roff .so 3/error.roff .so 3/warning.roff .so 3/mdoclint.roff .so 3/igor.roff .so 3/gmdiff.roff .so 3/consistency.roff eurobsdcon2014-mandoc-slides/3/consistency.roff010064400017500001750000000016441241000373000224450ustar00ischwarzeischwarze.GPE_NEXT "What about badly installed manuals?" "3.7:17" .GPE_MULB 12c 0v .TITLE "Installation checking" .SUBTITLE "with makewhatis(8) -p" .BL .LI Mismatch of the section number .br given in the manual page with .br the directory the page is stored in. .LI Mismatch of the architecture name .br given in the manual page with .br the directory the page is stored in. .LI Missing NAME section, missing name(s) .br and/or missing description. .LI File name does not appear .br as a name in the NAME section. .LI A name in the name section does not .br appear as an MLINK in the file system. .LE .MULN .PSPIC Images/AugustusHamiltonMoa.eps .ce 2 .GPE_SM "Moa hunt in the Dunedin Public Gardens" .GPE_SM "\(co 1906 Augustus Hamilton (PD)" .MULE .BL .LI Besides, direct inspection of the database has been used to catch markup errors. .LI More can be done later, all this is \m[red]just a start\m[]. .LE .GPE_TIME 120 "BSDCan 2014 p. 24" eurobsdcon2014-mandoc-slides/3/design.roff010064400017500001750000000015601240640615200213640ustar00ischwarzeischwarze.GPE_NEXT "Why does the design of -Tlint messages matter?" "3.1:13" .TITLE "Why it is critical to get errors and warnings right" .BVL 5n .LI "A fatal error gets thrown:" The manual doesn't format at all, which is very inconvenient. .LI "An error message is missing or too generic:" Users have a hard time to fix their errors. .LI "A warning message is missing:" Users don't even notice their dangerous idioms. .LI "A few warnings too many, or too prominent:" Users get annoyed and switch off all warnings. .LI "More than one or two knobs:" Users don't remember and don't use them. .LE .P Too few and too many can happen all at once! .br It did with mandoc, and it had too many knobs - at first. .P There were several major cleanups in mandoc: July 2009, May 2010, August 2010, October 2010, January 2011, March 2011, July 2014, ... .GPE_TIME 150 "BSDCan 2011 p. 21 (updated)" eurobsdcon2014-mandoc-slides/3/goals.roff010064400017500001750000000014171240731262400212220ustar00ischwarzeischwarze.GPE_NEXT "Are your manuals good?" "3.2:13" .TITLE "Goals of quality control for manuals" .BL .LI Find fatal errors, make sure all manuals actually produce output. .LI Make sure all intended content is actually shown. .LE .GPE_MULB 9c .BL .LI Catch severe formatting errors. .LI Catch typos .br and stylistic glitches. .LI Improve portability .br (but don't overdo this). .LI Improve robustness. .LI Unify display style. .LI Improve mdoc(7) coding style. .LI Find formatter bugs. .LE .MULN .PSPIC Images/DeyanVasilevTumba.eps .ce 2 .GPE_SM "\f[CYR]Tumba 1880m, Belasica\fP" .GPE_SM "\(co 2009 \f[CYR]De\(yan Vasilev\fP @wikimedia (CC)" .MULE .P Various tools are available, and some tasks require manual checking. .P The most important tool is .B "mandoc -Tlint" . .GPE_TIME 150 NEW eurobsdcon2014-mandoc-slides/3/mdoclint.roff010064400017500001750000000014111241000231200217000ustar00ischwarzeischwarze.GPE_NEXT "Are there other tools?" "3.4:16" .TITLE "Checking with mdoclint" .BL .LI Author: Thomas Klausner .LI similar focus as .B "mandoc -Tlint" : syntax .LI much fewer tests than mandoc(1) .LI used to contain some additional tests .LI .GPE_EM "most of these have recently been added to mandoc(1)" .LI also tries to avoid false positives, though not quite as strictly .B "mandoc -Tlint" .LI Do not slavishly follow its findings! .sp .LI available on NetBSD (pkgsrc/textproc/mdoclint) .br and OpenBSD (src/regress/usr.bin/mdoclint) .LI ought to be trivial to port to other systems providing perl(1) .sp .LI To run it, give the names of the files you want to check on the command line. .LI main purpose of options: suppress some messages .LE .GPE_TIME 60 NEW eurobsdcon2014-mandoc-slides/3/fatal.roff010064400017500001750000000020161240731455400212040ustar00ischwarzeischwarze.GPE_NEXT "Getting started with mandoc -Tlint" "3.3.1:14" .TITLE "Catching fatal errors" .GPE_MULB 12c .VERBON 0 20 mandoc -Tlint -Wfatal * .VERBOFF .BL .LI fatal errors abort the parser, .br no formatted output at all .LI consequently, a manual with a fatal error .br is not much better than none at all .LI in a large tree, handle these first, .br before anything else .LI can be skipped when checking .br just a few manuals, see next slide .LE .MULN .PSPIC Images/KirilRusevKutelo.eps .ce 2 .GPE_SM "\f[CYR]Kutelo 2908m i Vihren 2914m, Pirin\fP" .GPE_SM "\(co 2010 \f[CYR]Kiril Rusev\fP @flickr (CC)" .MULE .P Relevant fatal errors in practice \(em all related to file inclusion: .BL \n(Pi 1 .LI use of the unsafe macro .B Bd .B -file .LI use of the .B so file inclusion request with an absolute path .LI use of .B so with a path containing ".." .LI .B so pointing to a file that doesn't exist or can't be opened .LE .P See the mandoc(1) manual in the portable mandoc distribution for details, section "FATAL errors". .GPE_TIME 90 NEW eurobsdcon2014-mandoc-slides/3/error.roff010064400017500001750000000015541240640344300212470ustar00ischwarzeischwarze.GPE_NEXT "What about non-fatal problems?" "3.3.2:15" .TITLE "Catching errors" .VERBON 16 mandoc -Tlint -Werror * .VERBOFF .BL .LI may cause loss of information or severe misformatting .LI almost always needs fixing, trying hard to avoid false positives .LE .P Classification: .BL .LI unencoded non-ASCII characters in the input .LI unknown or mistyped macro or request names .LI blocking issues: .BL \n(Pi 1 .LI opening blocks that are never closed again .LI closing blocks that were never opened .LI items outside lists .LI bad nesting of blocks that don't support it .LE .LI severe issues with macro or request arguments: .BL \n(Pi 1 .LI missing essential arguments .LI invalid arguments that cannot be handled adequately .LI excessive arguments that get completely lost during formatting .LE .LE .P Again, see mandoc(1), section ERRORS, for a full list. .GPE_TIME 100 NEW eurobsdcon2014-mandoc-slides/3/warning.roff010064400017500001750000000021041240731342200215510ustar00ischwarzeischwarze.GPE_NEXT "What are warnings?" "3.3.3:15" .TITLE "Mandoc warnings" .GPE_MULB 13c 1v .VERBON 16 20 mandoc -Tlint * .VERBOFF .BL .LI everything else mandoc considers problematic .LI expect lots of output in a low-quality tree .LI false positives are rare, but a few do happen .LI use your judgement, do not blindly follow it .LE .MULN .PSPIC Images/GerovitusBotev.eps .ce 2 .GPE_SM "\f[CYR]Botev 2376m, Stara Planina\fP" .GPE_SM "\(co 2010 Gerovitus91 @wikimedia (CC)" .MULE .sp -0.5v The most important classes are: .BL \n(Pi 1 .LI structural errors and syntax errors that only have local effects and do not cause information loss .LI low quality syntax like badly nested blocks or macro usage in contexts expecting plain text .LI macros that have no effect or are slightly misplaced .LI missing arguments or information, if the effect is only local .LI violations of usual structural or formatting conventions .LI warnings about robustness and portability .LI dubious usage of white space and comments .LE .P Again, all warnings are listed in the portable mandoc(1) manual. .GPE_TIME 100 NEW eurobsdcon2014-mandoc-slides/3/igor.roff010064400017500001750000000013611241000250300210350ustar00ischwarzeischwarze.GPE_NEXT "What about style and spelling?" "3.5:16" .TITLE "Checking with igor(1)" .BL .LI Author: Warren Block (FreeBSD) .LI completely different focus: style and spelling, knows little about syntax .LI not afraid of false positives \(em bad for bulk checks: noise! .LI .GPE_EM "good to find candidates of bad style or spelling\ in smaller sets of manuals" .LI finds whole classes of issues the two linters are completely unaware of .LE .PSPIC Images/Igor.eps 10c .BL .LI available as a port in both FreeBSD and OpenBSD (textproc/igor) .LI should also be trivial to port to any system having perl(1) .LI provide the names of the files to be checked as command line arguments .LI command line options to suppress unwanted messages .LE .GPE_TIME 90 NEW eurobsdcon2014-mandoc-slides/3/gmdiff.roff010064400017500001750000000015371240731047300213540ustar00ischwarzeischwarze.GPE_NEXT "How do you catch rendering details?" "3.6:16" .TITLE "Groff-mandoc comparisons" .BVL 5n .LI "most useful to find parser and formatter bugs" .BL .LI This part is usually straightforward to interpret. .LE .LI "may also provide hints that code is of limited portability" .BL .LI This part requires wide experience with the mdoc(7) language: .LI Just because it formats differently doesn't mean it's bad code! .LE .LE .GPE_MULB 10c 0v .sp .ce .B gmdiff .BL .LI very short and simple .br but handy shell script .br to run such comparisons .LI available from .br the portable mandoc repository .LI provide the names .br of the files to check .br as command line arguments .LE .MULN .PSPIC Images/StelianKasabovMaljovitsa.eps .ce 2 .GPE_SM "\f[CYR]Malyovica 2729m, Rila\fP" .GPE_SM "\(co 2007 \f[CYR]Steli\(yan Kasabov\fP @flickr (PD)" .MULE .GPE_TIME 70 NEW eurobsdcon2014-mandoc-slides/4004075500017500001750000000000001241203076600171615ustar00ischwarzeischwarzeeurobsdcon2014-mandoc-slides/4/section.roff010064400017500001750000000005451241203036000215510ustar00ischwarzeischwarze.\" How to use the mandoc-based apropos(1) search tool .\" and how to build its databases with makewhatis(8). .\" .GPE_SECTION APROPOS .so 4/traditional.roff .so 4/semantic.roff .so 4/intermediate.roff .so 4/complex.roff .so 4/outkey.roff .so 4/man.roff .so 4/input.roff .so 4/output.roff .so 4/why_man.roff .so 4/name.roff .so 4/issues.roff .so 4/cgi.roff eurobsdcon2014-mandoc-slides/4/traditional.roff010064400017500001750000000021211241203040100224030ustar00ischwarzeischwarze.GPE_NEXT "How does searching work?" "4.1:18" .TITLE "Searching for manual pages" .sp -1.5v .SUBTITLE "Traditional functionality is preserved" .sp -0.5v .BVL 1c .LI "apropos \fIkeywords\fP ..." Search case-insensitively for substrings in names and descriptions. .LI "man \-k \fIarguments\fP" As before, an alias for: apropos \fIarguments\fP .br But now also supports new-style arguments, see below. .LI "apropos [\fB\-C \fIfile\fR] [\fB\-M \fIpath\fR] [\fB\-m \fIpath\fR] \ [\fB\-S \fIarch\fR] [\fB\-s \fIsection\fR] \fIkeywords\fR ..." Traditional options are all supported. .LE .GPE_MULB 12c .BVL 1c .LI "whatis \fIkeywords\fP ..." Search case-insensitively for complete .br words in page names only. .LI "makewhatis" Rebuild all configured databases. .LI "makewhatis \-d \fIdirectory files ...\fP Update entries for the given \fIfiles\fP .br in one database. .LE .P .ce .GPE_EM "backward compatible" .sp -2v .MULN .PSPIC Images/GlenFergusKiwi.eps .ce 2 .GPE_SM "Southern Kiwi / Tokoeka (Apteryx australis)" .GPE_SM "\(co 2008 Glen Fergus @wikimedia (CC)" .sp -2v .MULE .GPE_TIME 60 "BSDCan 2014 p. 12" eurobsdcon2014-mandoc-slides/4/semantic.roff010064400017500001750000000023531240640624300217210ustar00ischwarzeischwarze.GPE_NEXT "New functionality" "4.2:18" .TITLE "Markup-sensitive search" .sp -1v .VERBON 0 12 $ apropos Ev=USER Mail, mail, mailx(1) \(en send and receive mail csh(1) \(en a shell (command interpreter) with Clike syntax login(1) \(en log into the computer logname(1) \(en display user's login name slogin, ssh(1) \(en OpenSSH SSH client (remote login program) su(1) \(en substitute user identity [...] .VERBOFF .sp 0.2v Macro keys that can be searched for (examples, ordered by frequency): .GPE_MULB 5i .S -4 .VL 2c 0c 1 .LI Nm manual page names .LI Nd manual page descriptions .LI sec manual section numbers .LI arch machine architectures .LI Xr cross references .LI Ar command argument names .LI Fa function argument types and names .LI Dv preprocessor constants .LI Pa file system paths .LI Cd kernel configuration directives .LI Va variable names .LI Ft function return types .LI Er error constants .LI Ev environment variables .LI In include file names .LI St references to standards documents .LI An author names .LI ... and so on ... .LE .S +4 .MULN .PSPIC Images/JJHarrisonSilvereye.eps (u;\n(.l-\n(.i)u .ce 2 .GPE_SM "Silvereye / Tauhou (Zosterops lateralis)" .GPE_SM "\(co 2008 J. J. Harrison @wikimedia (CC)" .MULE .GPE_TIME 60 "BSDCan 2014 p. 13" eurobsdcon2014-mandoc-slides/4/intermediate.roff010064400017500001750000000033151240640627200225710ustar00ischwarzeischwarze.GPE_NEXT "Intermediate new search features" "4.3:19" .TITLE "Markup-sensitive search features" Search keys can be OR'ed: .VERBON 6 12 $ apropos \m[red]Fa,Ft,Va,Vt=\m[]timespec EV_SET, kevent, kqueue(2) \(en kernel event notification mechanism clock_getres, clock_gettime, clock_settime(2) \(en get/set/calibrate date and time futimens, futimes, utimensat, utimes(2) \(en set file access and modification times nanosleep(2) \(en high resolution sleep parse_time(3) \(en parse and unparse time intervals poll, ppoll(2) \(en synchronous I/O multiplexing pselect, \m[red]select(2)\m[], FD_CLR, FD_ISSET, FD_SET, \ \m[red]FD_ZERO(3)\m[]\ \(en synchronous I/O multiplexing sem_timedwait, sem_trywait, sem_wait(3) \(en decrement (lock) a semaphore tstohz, tvtohz(9) \(en translate time period to timeout delay [...] .VERBOFF Searching across all keys is possible: .VERBON 6 12 $ apropos \m[red]any=\m[]ulimit ksh, rksh(1) \(en public domain Korn shell sh(1) \(en public domain Bourne shell getrlimit, setrlimit(2) \(en control maximum system resource consumption .VERBOFF Regular expressions are supported (\(oq~\(cq instead of \(oq=\(cq) since October 19, 2013: .VERBON 6 12 $ apropos "Nm~^[gs]et.*gid" endgrent, getgrent, getgrgid, getgrgid_r, getgrnam, getgrnam_r, setgrent, setgrfile, setgroupent(3) \(en group database operations getegid, getgid(2) \(en get group process identification getpgid, getpgrp(2) \(en get process group getresgid, getresuid, setresgid, setresuid(2) \(en get or set real, effective and saved user or group ID setegid, seteuid, setgid, setuid(2) \(en set user and group ID setpgid, setpgrp(2) \(en set process group setregid(2) \(en set real and effective group IDs [...] .VERBOFF .GPE_TIME 50 "BSDCan 2014 p. 14" eurobsdcon2014-mandoc-slides/4/complex.roff010064400017500001750000000027031240640630200215600ustar00ischwarzeischwarze.GPE_NEXT "Advanced new search features" "4.4:19" .TITLE "Complex search queries" By default, multiple search terms are joined with OR, .br but the .B \-s and .B \-S options attach to the rest of the search expression with AND: .VERBON 6 12 $ apropos \-s 1 tbl Nm=eqn deroff(1) \(en remove nroff/troff, eqn, pic and tbl constructs eqn(1) \(en format equations for troff or MathML eqn2graph(1) \(en convert an EQN equation into a cropped image neqn(1) \(en format equations for ascii output tbl(1) \(en format tables for troff .VERBOFF .sp 1v .GPE_MULB 15.5c Explicit logical AND and OR are supported: .VERBON 6 12 $ apropos Nd=gigabit \m[red]\-a\m[] Cd=sbus gem(4) \(en GEM 10/100/Gigabit Ethernet device ti(4) \(en Alteon Networks Tigon I and II Gigabit Ethernet device .VERBOFF Precedence can be changed with parantheses: .VERBON 6 12 $ apropos \-s 1 terminal \m[red]\-a\ \e(\m[] At~[1\-6] \m[red]\-o\m[] Bx~^[12] \m[red]\e)\m[] clear, tput(1) \(en terminal capability interface lock(1) \(en reserve a terminal reset, tset(1) \(en terminal initialization script(1) \(en make typescript of terminal session stty(1) \(en set the options for a terminal device interface tty(1) \(en return user's terminal name .VERBOFF .sp 1v Complex search queries are working since January 4, 2014. .MULN .PSPIC Images/AvicedaMorepork.eps .ce 3 .GPE_SM "Morepork / Ruru \(co 2005" .GPE_SM "(Ninox novaeseelandiae)" .GPE_SM "Aviceda@wikimedia (CC)" .MULE .GPE_TIME 50 "BSDCan 2014 p. 15" eurobsdcon2014-mandoc-slides/4/outkey.roff010064400017500001750000000017371240640632000214370ustar00ischwarzeischwarze.GPE_NEXT "New output features" "4.5:20" .TITLE "Flexible output format" .sp -1v .BL .LI The names, section numbers, and architectures of the search results are always shown because these are needed to access the results with man(1). .LI By default, apropos(1) also shows the one-line descriptions. .LE .sp 0.5v With the .B \-O option, any other macro key can be shown instead: .VERBON 6 12 $ apropos \-O Cd wireless acx(4) \(en acx* at pci? # acx* at cardbus? an(4) \(en an* at isapnp? # an* at pcmcia? # an* at pci? ath(4) \(en ath* at pci? dev ? function ? # ath* at cardbus? dev ? function ? # gpio* at ath? athn(4) \(en athn* at cardbus? # athn* at uhub? port ? # athn* at pci? atu(4) \(en atu* at uhub? port ? atw(4) \(en atw* at pci? # atw* at cardbus? .VERBOFF The .B \-O option is available since December 31, 2013. .PSPIC Images/SidMosdellBellbird.eps 8c .ce .GPE_SM "Bellbird / Korimako (Anthornis melanura)\ \(co 2012 Sid Mosdell @flickr (CC)" .GPE_TIME 50 "BSDCan 2014 p. 16" eurobsdcon2014-mandoc-slides/4/cgi.roff010064400017500001750000000021601240737340100206540ustar00ischwarzeischwarze.GPE_NEXT "Are manuals only available at the console?" "4.7:22" .TITLE "Web interface for manual search and display" .GPE_MULB 11.5c .BL .LI Same user interface as on the command line: man(1) and whatis(1) mode, same query syntax .LI Main additional feature: hyperlinks .LI Additional potential due to preserved semantic markup, not really used yet for anything except (simple) CSS formatting .LI Same directory structure and database format on the server .LI Configuration instructions in man.cgi(8) .LE .MULN .PSPIC Images/CharlesjsharpRedFoxKit.eps .ce 2 .GPE_SM "Red fox kit (Vulpes vulpes)" .GPE_SM "\(co 2014 Charlesjsharp @wikimedia (CC)" .MULE .sp 0.5v .BL .LI Useful mainly for providers of operating systems and large software packages. .LI Running your own copy of the manuals of your favourite system is a bad idea: .LI It will get outdated and confuse people. .LE .sp .ce .GPE_EM "Special thanks to \fIS\('ebastien Marie\fP:" He did an extensive security audit of the .Xr man.cgi 8 code and reported a considerable number of security-relevant bugs that have all been fixed by now. .GPE_TIME 180 "\m[red]SURPRISE TOPIC\m[]" eurobsdcon2014-mandoc-slides/4/output.roff010064400017500001750000000023641241203043700214530ustar00ischwarzeischwarze.GPE_NEXT "Which output options?" "4.6.1:21" .TITLE "Unified output options" Specify which kind of output to provide: .VL 6n 2n 1 .LI \fB\-a\fP Display all matching manual pages, one after the other. This is the default for .B \-l input mode. .LI \fB\-h\fP Display only the SYNOPSIS lines of the matching pages. Implies .B \-a . .LI \fB\-O\fP When showing a list in .B \-f or .B \-k mode, display the specified macro key instead of the .B Nd one-line descriptions. .LI \fB\-w\fP Display only the pathnames of the matching manual pages. .LE .P Some .B "parser and formatter options" only take effect when a parser is actually run: .VL 6n 2n 1 .LI \fB\-I\fP Override the default operating system name for the mdoc(7) .B Os macro. .LI \fB\-m\fP Specify the input format. Defaults to .B \-mandoc , requesting autodetection. .LI \fB\-O\fP Comma-separated formatter-specific output options. .LI \fB\-T\fP Select the output format. Defaults to .B \-Tascii . .LI \fB\-W\fP Specify the minimum message .I level to be reported on the standard error output and to affect the exit status. Defaults to .B \-Wfatal . .LE .P Finally, the .B \-c option can be used to suppress the pager and just copy the formatted manuals to standard output. .GPE_TIME 90 "\m[red]SURPRISE TOPIC\m[]" eurobsdcon2014-mandoc-slides/4/man.roff010064400017500001750000000015421240731606100206670ustar00ischwarzeischwarze.GPE_NEXT "Can we use all that for man(1), too?" "4.6:20" .TITLE "Unified user interface including man(1)" .GPE_MULB 12c 1v .sp 0.5v .BL .LI man(1) now included .br in the mandoc toolbox .LI unified user interface for .br mandoc(1), man(1), whatis(1), apropos(1) .LI same command line options for all .LI still different default behaviour .LE .MULN .PSPIC Images/MattyMusala.eps .ce 2 .GPE_SM "\f[CYR]Musala 2925m, Rila\fP" .GPE_SM "\(co 2007 mattyhike @flickr (CC)" .MULE .sp 0.5v .ce .GPE_EM "Steps taken by the unified main program:" .sp -0.5v .AL .LI Decide how to interpret the command line arguments. .LI Build a list of manual pages, usually from a database search. .LI Decide which kind of output to provide. .LI Optionally spawn a pager. .LI Loop around the list of manual pages, producing some output for each. .LE .GPE_TIME 90 "\m[red]SURPRISE TOPIC\m[]" eurobsdcon2014-mandoc-slides/4/input.roff010064400017500001750000000022141241000431000212310ustar00ischwarzeischwarze.GPE_NEXT "Which options?" "4.6.1:21" .TITLE "Unified input options" Specify the meaning of the command line arguments: .VL 6n 2n 1 .LI \fB\-l\fP command line arguments = filenames (no database search) .br This is the default when called as .B mandoc . .LI * The default when called as .B man : .br command line arguments = names (for exact matches) .br default output mode: show exactly one manual (best match) .LI \fB\-f\fP command line arguments = names (for complete word search) This is the default when called as .B whatis . .LI \fB\-k\fP Support the full .B apropos search syntax. .br default output mode: list of title lines .LE .P Some .B "database selection" options only matter when .B \-l is not active: .VL 6n 2n 1 .LI \fB\-C\fP Use the specified .I file instead of the default configuration file. .LI \fB\-M\fP Use the specified .I path instead of the default one. Do not use any configuration file. .LI \fB\-m\fP Use the specified .I path in addition to the default one. .LI \fB\-S\fP Restrict the search to the specified .I architecture . .LI \fB\-s\fP Restrict the search to the specified .I section . .LE .GPE_TIME 90 "\m[red]SURPRISE TOPIC\m[]" eurobsdcon2014-mandoc-slides/4/why_man.roff010064400017500001750000000023121241000677300215520ustar00ischwarzeischwarze.GPE_NEXT "How did this happen?" "4.6.2:21" .TITLE "Nothing planned, just for fun!" Four months back at BSDCan 2014 in Ottawa, i presented a slide "possible future directions". This project was .I not listed. I didn't expect myself that i would do this. .P .ll -2c .in +2c \(lqAre there any plans for providing a man(1) command also? .br This would make mdocml a possible, standalone replacement for the groff and man-db combination (typical in Linux distributions).\(rq .ce .GPE_EM "\(em Paul Onyschuk (Alpine Linux), August 9, 2014" .in -2c .ll +2c .sp -0.5 .GPE_MULB 13.2c .BL .LI First impulse: return standard negative answer. .LI \&... .LI Suddenly realized almost all code already there! .LI Needed just a bit of code reshuffling... .LI Had to do the 1.13.1 and 1.12.4 releases first. .LI \&... so in the end, it took about two weeks: .VL 8n 1 .LI "Aug 9" idea .LI "Aug 21" first working version .LI "Aug 26" unified interface in OpenBSD .LE .LE .sp 0.5v Since man(1) is not production quality yet, .br it is not yet used by default in OpenBSD. .MULN .PSPIC Images/GaryTannerFoal.eps .ce 2 .GPE_SM "Foals Just Wanna Have Fun" .GPE_SM "\(co 2009 Gary Tanner @flickr (CC)" .MULE .GPE_TIME 120 "\m[red]SURPRISE TOPIC\m[]" eurobsdcon2014-mandoc-slides/4/name.roff010064400017500001750000000016421240741576100210440ustar00ischwarzeischwarze.GPE_NEXT "Are there any tricky points?" "4.6.3:21" .TITLE "What a \(oqname\(cq is" .BL .LI man(1) displays the manual with the given name. .LI .GPE_EM "Traditional man(1) only uses filenames as names in this sense." .LI makewhatis(8) adds names to the .I names table in the mandoc.db(5) databases. .LI The .I names.bits column tells where the name came from: .BL .LI .BR Dt / TH header line .LI .B Nm in the NAME section .LI .B Nm in the SYNOPSIS section .LI filename .LE .LI .GPE_EM "Right now, the mandoc version of man(1) uses all types of names." .LI That can and should be tuned! .LI Use .B Nm macros from the NAME section only? .LI That way, all hard links, symbolic links, and .so link files become obsolete. Consequently, the number of files in a typical operating system installation can be reduced by more than three thousands. .LI Continue to use filenames as a fallback? .LE .GPE_TIME 90 "\m[red]SURPRISE TOPIC\m[]" eurobsdcon2014-mandoc-slides/4/issues.roff010064400017500001750000000017101240727067300214340ustar00ischwarzeischwarze.GPE_NEXT "Any issues left?" "4.6.4:22" .TITLE "Remaining issues" .BVL \n(Pi .LI "option \fB-i\fP (interactive)" not yet integrated \(em old manpage(1) utility was never used .LI man.conf(5) .BL \n(Pi 1 .LI ignored: .B _build , .B _default , .B _subdir , .B _suffix , .I section .LI using .B _whatdb instead of .B _default .LI hardcoded subdirectories: \f(CW{man,cat}N\fP .LI hardcoded search order: 1, 8, 6, 2, 3, 5, 7, 4, 9 .LE .LI "MACHINE environment variable" not supported (and not really useful?) .br But uname(3) should be used to select the right architecture! .LI "manual selection:" When finding a formatted and an unformatted manual of the same name in the same section, the old man(1) shows the one that was less recently changed. The mandoc man(1) currently always prefers the unformatted version, even if it's older than the formatted version. .LI "additional results" for bogus names, see previous slide .LE .GPE_TIME 90 "\m[red]SURPRISE TOPIC\m[]" eurobsdcon2014-mandoc-slides/5004075500017500001750000000000001240704177400171675ustar00ischwarzeischwarzeeurobsdcon2014-mandoc-slides/5/section.roff010064400017500001750000000005041240704176000215570ustar00ischwarzeischwarze.\" How to effectively integrate mandoc(1) as a manual formatter .\" and manual page search system into the base system of a BSD .\" operating system and what to pay attention to while doing so .\" .GPE_SECTION BASE .so 5/start.roff .so 5/fatal.roff .so 5/errors.roff .so 5/compare.roff .so 5/switch.roff .so 5/regress.roff eurobsdcon2014-mandoc-slides/5/start.roff010064400017500001750000000016071240642034600212550ustar00ischwarzeischwarze.GPE_NEXT "How does system integration work?" "5.1.2:26" .TITLE "Getting started with base integration" .GPE_MULB 11c .BL .LI Import mandoc into the base tree. .LI Collect initial experience with mandoc. .LI Report bugs and get them fixed. .LI Establish the contact .br to everybody who is interested. .LI Get familiar with specific requirements of the system in question and specific topics the developers are concerned about. Do not neglect this aspect or it will bite you later. .LE .MULN .PSPIC Images/KrisVoordenFoal.eps .ce 3 .GPE_SM "New Forest Foal" .GPE_SM "\(co 2010 Krista van der Voorden @flickr (CC)" .GPE_EM "Don't be lazy, get moving..." .MULE .BL .LI In OpenBSD, this phase lasted from June to December 2009. .LI Because mandoc has matured, it is much easier now. .LI In any case, this phase can be shorter. .LI Start the next phase early! .LE .GPE_TIME 120 "BSDCan 2011 p. 5 (updated)" eurobsdcon2014-mandoc-slides/5/fatal.roff010064400017500001750000000013331240705237700212110ustar00ischwarzeischwarze.GPE_NEXT "What's the first step for systematic integration?" "5.2:27" .TITLE "Identify fatal issues" .GPE_MULB 12c 0v .sp .BL .LI Try to build the whole tree. .LI Ignore all non-fatal issues for now. .LI Report all fatal errors upstream. .LI Have them fixed upstream .br or devise workarounds. .br We are glad to provide help! .LI Only as a last resort, .br change the affected manuals. .sp .LI In OpenBSD, this phase took place .br in January and February 2010. .LI Ought to be much easier now: .LE .MULN .PSPIC Images/TambakoZebra.eps .ce 2 .GPE_SM "Very young zebra" .GPE_SM "\(co 2009 Tambako @flickr (CC)" .MULE .sp 2v .ce .GPE_EM "mandoc hardly throws any fatal errors any longer" .GPE_TIME 120 "BSDCan 2011 p. 6 (updated)" eurobsdcon2014-mandoc-slides/5/errors.roff010064400017500001750000000017121240640712600214320ustar00ischwarzeischwarze.GPE_NEXT "What about manuals that fo build?" "5.3:28" .TITLE "Investigate non-fatal errors" .BL .LI Run "mandoc -Tlint -Werror". .LI Prioritize fallout that ruins content or formatting. .LI Distinguish mandoc bugs from markup bugs. .LI Report mandoc bugs upstream. Typical areas: Missing low-level roff(7) functionality. Undefined macros. .LI Watch out for home-grown non-standard features used in your tree. This also applies to the next phase. .LI Watch out for tbl(7). If some of those don't work yet, as a last resort, you might continue to build those with groff at first. .LI Fix ruinous markup bugs in your tree. Do not change manuals to work around mandoc bugs. .LI Don't let non-critical markup bugs overwhelm you. Postpone fixing them if they cause too much slowdown. .LI In OpenBSD, the equivalent happened in March 2010. Some parts were postponed to June 2010, after the switch. The OpenBSD tbl(7) pages were switched in October 2010. .LE .GPE_TIME 180 NEW eurobsdcon2014-mandoc-slides/5/compare.roff010064400017500001750000000016711240640723700215530ustar00ischwarzeischwarze.GPE_NEXT "Final checks before the switch..." "5.4:31" .TITLE "Check mandoc output" .BL .LI For the manuals in your tree, systematically compare groff(1) and mandoc(1) output. .LI Use gmdiff. .LI Look at the patches to textproc/groff in OpenBSD ports. .LI The comparison will not be quite easy because there will be some noise, most of it about whitespace. .LI Won't become completely identical, but try to make sure no content gets lost and no formatting is completely garbled. .LI If you find any serious issues, report them, in particular if mandoc(1) fails to flag them as ERRORs. .LI Patching manuals is usually not the right approach in this phase. .LI Quickly move on to the next phase, that is, when you are convinced there are no show-stopper issues, not when you feel everything is perfect. Your system will mature best when it's enabled by default and when you get and use real-world feedback. .LE .GPE_TIME 180 "BSDCan 2011 p. 16 (updated)" eurobsdcon2014-mandoc-slides/5/switch.roff010064400017500001750000000014351240704163000214140ustar00ischwarzeischwarze.GPE_NEXT "Ready for switching?" "5.6:32" .TITLE "Switch over the tree" .GPE_MULB 10c .BL .LI Make sure there is plenty of time until the next release. .LI Watch out for bug reports from users of -current. .LI Report and fix bugs as quickly as possible. .LI It can be done in one or two steps. .LE .MULN .PSPIC Images/TinyPackagesRoadside.eps .ce 2 .GPE_SM "On the Road" .GPE_SM "\(co 2010 tiny_packages @flickr (CC)" .MULE .sp -1v .BL .LI OpenBSD did it in two steps: .br Change the formatter in April 2010. .br Install source manuals since October 2010. .LI NetBSD did it in one step in February 2012. .LI One-step process is recommended if you feel confident you can handle it. .LI Two-step process is slightly more prudent but causes more work. .LE .GPE_TIME 180 "BSDCan 2011 p. 11 (updated)" eurobsdcon2014-mandoc-slides/5/regress.roff010064400017500001750000000015341240704742000215700ustar00ischwarzeischwarze.GPE_NEXT "More tools to make sure it works?" "5.1.3:26" .TITLE "Regression testing" .BL .LI A regression suite does exist. .LI Tightly tied into the OpenBSD regression system. .LI It would be useful to get it running elsewhere. .LI Do .I not copy and change it: A maintenance nightmare would ensue! .LE .GPE_MULB 14c 0v .sp Not at all for portable make(1), it requires: .BL .LI in assignments: \f(CW?= += !=\fP .LI in variable expansion: \f(CW:C :M :S\fP .LI control statements: \f(CW.if .else .for\fP .LI in conditionals: .br \f(CWdefined() empty() target()\fP .LI BSD make(1) modules: bsd.subdir.mk bsd.obj.mk bsd.regress.mk bsd.prog.mk bsd.own.nk .sp .LI This list incomplete. .LI Not sure yet how to proceed... .LE .MULN .PSPIC Images/JeffBurcherHorseFly.eps .ce 2 .GPE_SM "Horse Fly" .GPE_SM "\(co 2010 Jeff Burcher @flickr (CC)" .MULE .GPE_TIME 120 NEW eurobsdcon2014-mandoc-slides/6004075500017500001750000000000001240036130500171545ustar00ischwarzeischwarzeeurobsdcon2014-mandoc-slides/6/section.roff010064400017500001750000000005141241203050700215520ustar00ischwarzeischwarze.\" How to effectively use mandoc(1) as a manual formatter and manual .\" page search system in a porting and packaging framework, and what .\" to do about manuals that require groff(1) for correct formatting. .\" .GPE_SECTION PORTS .so 6/problem.roff .so 6/solution.roff .so 6/evolution.roff .so 6/makewhatis.roff .so 6/start.roff eurobsdcon2014-mandoc-slides/6/problem.roff010064400017500001750000000017741240640737500215750ustar00ischwarzeischwarze.GPE_NEXT "What about ports manuals?" "6.1:34" .TITLE "Handling manual pages in ports" .SUBTITLE "The problem" .BVL 1c .LI "The Law of Feature Creep" If a software offers some feature, sooner or later somebody will use it. .LI "Porting corollary" For every feature of the roff language (and for every groff extension), no matter how arcane and how obviously irrelevant for manual pages, sooner or later somebody will want to port a third-party software abusing that feature to format its manual pages. .LI "mandoc(1) is not a complete nroff implementation" and who knows whether it will ever be... .LI "Not a problem in the base system:" Given a finite set of manuals, implement in mandoc(1) what is needed, or patch away the worst abuse in the handful of manuals affected. .LI "\m[red]But in ports, \(lqmandoc or nothing\(rq is not a viable\ strategy:\m[]" That would inevitably leave you with some seriously misformatted manuals, and in some cases with no usable manuals at all. .LE .GPE_TIME 120 "BSDCan 2014 p. 30" eurobsdcon2014-mandoc-slides/6/solution.roff010064400017500001750000000025601240640742700220010ustar00ischwarzeischwarze.GPE_NEXT "How can this be solved?" "6.2:34" .TITLE "The OpenBSD solution for manual pages in ports" .sp -1v .BL .LI Make sure that no port tries to preformat manuals during the build target. .LI Let every port install manual page sources during the fake install target. .LI For the majority of ports, mandoc(1) can handle all manuals: .br That's it, you are done with respect to these. .LI For the remaining minority of ports: Set a special boolean make(1) variable in the port Makefile, in OpenBSD called USE_GROFF. .LI That variable implies a build dependency on the groff port. .LI .GPE_EM "When building the package, the ports framework runs groff on the\ fly and packages the preformatted pages instead of the source pages." .LI After installing the packages, this will work just fine at run time: The preformatted pages will be diplayed directly by man(1), and man(1) will format the source pages with mandoc(1), with no dedicated configuration. .LI .\" main topic (quoted) Example of OpenBSD: 7952 ports, 1217 still USE_GROFF (15%). .br Some of these probably don't really need it, but there is no hurry. .br Removing USE_GROFF needs a manual check \(em which was already done for about 3000 ports during the last three years. .LI This concept has been designed and implemented by Marc Espie, and it has proven very sturdy and very easy to use. .LE .GPE_TIME 180 "BSDCan 2014 p. 31" eurobsdcon2014-mandoc-slides/6/makewhatis.roff010064400017500001750000000021671240640751500222630ustar00ischwarzeischwarze.GPE_NEXT "makewhatis(8) in ports" "6.4:35" .TITLE "makewhatis(8) in ports" .BL .LI Base and X manual databases are essentially static. .LI But packages get installed and deinstalled. .LI You could wait for the periodic weekly(8) makewhatis(1) rebuild. .LI Better idea: .br During pkg_add, run \f(CWmakewhatis -d /usr/local/man files ...\fP .br During pkg_delete, run \f(CWmakewhatis -u /usr/local/man files ...\fP .LI Done routinely on OpenBSD, works seamlessly with the new makewhatis. .LI .GPE_EM "So, right after pkg_add(1), you call apropos(1),\ and it finds the freshly installed manual pages." .LE .GPE_MULB 14.5c 1.5v .SUBTITLE "Features that help, in particular for ports" .BL .LI Handle preformatted manuals (since Nov. 27, 2011). .LI Natively support gzip(1)'ed manual pages .br (since March 26, 2014). .LI During makewhatis -d/-u, automatically rebuild .br missing or corrupt databases (since April 18, 2014). .LE .MULN .PSPIC Images/SidMosdellKakariki.eps .ce 3 .GPE_SM "Red-crested parakeet / Kakariki" .GPE_SM "(Cyanoramphus novaezelandiae)" .GPE_SM "\(co 2010 Sid Mosdell @flickr (CC)" .MULE .GPE_TIME 180 "BSDCan 2014 p. 32" eurobsdcon2014-mandoc-slides/6/evolution.roff010064400017500001750000000023031240640746500221460ustar00ischwarzeischwarze.GPE_NEXT "Is there anything that helps?" "6.3:34" .TITLE "Continuous evolution of mandoc(1)" .sp -0.5v .BL .LI Indirect references in roff(7) expansion since April 7, 2014. .LI Expansion of roff(7) number registers since March 21, 2013 (Christos Zoulas). .LI Almost complete support for roff(7) numerical expressions since April 7, 2014. .LI Numeric comparison in roff(7) conditionals since April 3, 2013 (Chr. Zoulas). .LI String comparison in roff(7) conditionals since March 8, 2014. .LE .GPE_MULB 14c .BL .LI Newly supported roff(7) requests: .DS .ta 6c \&.as\~(append to string) .cc\~(control character) \&.it\~(input line trap) .ll\~(line length) \&.rr\~(remove register) .tr\~(character translation) .DE .LI newly supported man(7)-ext macros: .DS \&.EX/.EE (example display) \&.OP (optional element) \&.PD (paragraph distance) \&.UR/.UE (uniform resource identifier) .DE .LI Lots of bugfixes and formatting corrections. .LE .MULN .PSPIC Images/BrendaAndersonFantail.eps .ce 2 .GPE_SM "\h'-0.8c'Fantail / Piwakawaka (Rhipidura fuliginosa)" .GPE_SM "\h'-0.4c'\(co 2007 Brenda Anderson @flickr (CC)" .MULE .P .ce .GPE_EM "Matured considerably in addition to growing new features." .GPE_TIME 90 "BSDCan 2014 p. 37" eurobsdcon2014-mandoc-slides/6/start.roff010064400017500001750000000016521240640770700212640ustar00ischwarzeischwarze.GPE_NEXT "Step-by-step instructions?" "6.6:36" .TITLE "Getting started with ports" .BL .LI Build and commit a textproc/groff port (version 1.22.2), even if you have groff in base. .LI Introduce the USE_GROFF port Makefile variable. .LI Trigger a groff build dependency for USE_GROFF. .LI Implement format-on-the-fly for USE_GROFF and install formatted. .LI Without USE_GROFF, install source manuals. .LI Pay attention to get packing lists right. .LI Safe way: Turn USE_GROFF on for all ports having manuals. Shortcut: Skip those that don't have it in OpenBSD. .LI Remove groff from base. .LI Start removing USE_GROFF on a case by case basis. To be extra safe: Only do it for ports having no mandoc ERRORs and identical output with groff and mandoc. .LI This is another critical phase: Stay tuned for bug reports from users and work with upstream to get them resolved. .LI In OpenBSD, this happened in October 2010. .LE .GPE_TIME 150 NEW eurobsdcon2014-mandoc-slides/7004075500017500001750000000000001241203106500171555ustar00ischwarzeischwarzeeurobsdcon2014-mandoc-slides/7/section.roff010064400017500001750000000004151241203053400215530ustar00ischwarzeischwarze.\" Which next steps are recommended for the major BSD systems: .\" OpenBSD, NetBSD, FreeBSD, DragonFly, ... .\" .GPE_SECTION STATUS .so 7/openbsd_status.roff .so 7/netbsd_status.roff .so 7/freebsd_status.roff .so 7/nonbsd_status.roff .so 7/todo.roff .so 7/thanks.roff eurobsdcon2014-mandoc-slides/7/openbsd_status.roff010064400017500001750000000027171241063036400231600ustar00ischwarzeischwarze.GPE_NEXT "What is the status in various systems?" "7.1.1:37" .TITLE "Status in OpenBSD" .sp -0.5v .GPE_MULB 17c 2v .BL 3n 1 .LI Kristaps@ developed mandoc(1) since November 22, 2008. .LI Source code in the base repo since April 6, 2009. .LI Schwarze@ maintaining it since June 14, 2009. .LI Actively maintained regression suite since October 27, 2009. .LE .MULN .PSPIC Images/OpenBSD.eps .MULE .BL 3n 1 .LI mandoc(1) installed with OpenBSD-current since April 2, 2010. .LI Base system manuals built with mandoc(1) since April 3, 2010. .LI USE_GROFF framework for ports by espie@ since April 5, 2010. .LI Releases fully rely on mandoc(1) since OpenBSD 4.8, November 1, 2010. .LI Groff disconnected from base build since October 18, 2010: .br .GPE_EM "mandoc(1) is the only documentation formatter in base\ for almost four years." .LI Groff removed from the source tree since March 12, 2011. .LI Groff 1.21/1.22 available from the ports tree since March 19, 2011. .LI No stable releases contain groff since OpenBSD 4.9, May 1, 2011. .LI Install manual sources, not preformatted manuals since June 23, 2011. .sp .LI SQLite-based code in the source tree since December 30, 2013. .LI .GPE_EM "makewhatis(8)/apropos(1) using mandoc" since April 18, 2014. .LI All will be released with OpenBSD 5.6 on November 1, 2014. .LI New man.cgi(8) online on openbsd.org since July 12, 2014. .LI Unified interface for mandoc(1) and apropos(1) since August 26, 2014. .LE .GPE_TIME 90 "BSDCan 2014 p. 25" eurobsdcon2014-mandoc-slides/7/netbsd_status.roff010064400017500001750000000021621241063077700230070ustar00ischwarzeischwarze.GPE_NEXT "NetBSD" "7.2.1:38" .TITLE "Status in NetBSD" .GPE_MULB 15c .BL .LI A pkgsrc mdocml port by J\(:org Sonnenberger .br exists since March 1, 2009 \(-> .br continued support for \fImany\fP platforms. .LI The first code patch was sent upstream .br by J\(:org Sonnenberger on June 11, 2009. .LI Source code in the base repo and installed by default .br in NetBSD-current since October 21, 2009. .LE .MULN .PSPIC Images/NetBSD.eps .MULE .SUBTITLE "Big changes in NetBSD on February 7, 2012" .BL .LI .\" src/share/mk/bsd.own.mk#rev1.695 Install source manuals, no longer install preformatted manuals. .LI Use mandoc(1) as the default run-time manual formatter instead of groff. .LI Use makemandb(8) by Abhinav Upadhyay instead of makewhatis(8) .br together with versions of apropos(1) and whatis(1) based on it, .br featuring full text search, but not semantic search. .LE .P .GPE_EM "All this was first released with NetBSD 6.0 on October 17, 2012." .P .BL .LI Semantic searching is not yet supported, not even as an option. .LI Enabling it is very difficult because it clashes with makemandb(8). .LE .GPE_TIME 90 "BSDCan 2014 p. 26" eurobsdcon2014-mandoc-slides/7/freebsd_status.roff010064400017500001750000000020221241063123100231170ustar00ischwarzeischwarze.GPE_NEXT "FreeBSD and DragonFly" "7.3:38" .TITLE "Status in FreeBSD" .GPE_MULB 17.5c 3v .BL .LI An mdocml port by Ulrich Sp\(:orlein exists since March 9, 2009. .LI First code patch sent in by Ulrich Sp\(:orlein on July 18, 2009. .LE .MULN .PSPIC Images/FreeBSD.eps .MULE .BL .LI Source code in the base repo and installed by default since October 19, 2012. .LI .GPE_EM "First released with FreeBSD 10.0 on January 20, 2014." .LE .TITLE "Status in DragonFly BSD" .GPE_MULB 17.5c 2v .BL .LI Source code in the base repo and installed by default .br since October 27, 2009 (Sascha Wildner) .LI .GPE_EM "First released with DragonFly BSD 3.6.0 on March 28, 2010." .LE .MULN .PSPIC Images/DragonFly.eps .MULE .sp -1v .BL .LI First code patch sent in by Franco Fichtner on November 25, 2013. .LE .SUBTITLE "In both:" .BL .LI mandoc(1) is installed, but not used. .LI Semantic searching is not yet supported, not even as an option. .LI Suggested next steps: update to 1.13.1 and use it to format the manuals. .LE .GPE_TIME 120 "BSDCan 2014 p. 27" eurobsdcon2014-mandoc-slides/7/nonbsd_status.roff010064400017500001750000000040401241063273700230060ustar00ischwarzeischwarze.GPE_NEXT "Non-BSD systems" "7.5:39" .SUBTITLE "Status in non-BSD systems" .GPE_MULB 15c .BVL 1c .LI "illumos" .BL .LI Mandoc is contained in the base system .br .GPE_EM "and used by default for formatting manuals" .br since July 21, 2014 (Garrett D'Amore). .LI The first and so far only non-BSD system to .br accomplish this, and the third system grand total. .LE .LE .MULN .PSPIC Images/illumos.eps .MULE .sp -0.5v .BVL 1c .LI "Minix 3" .BL .LI Source code in the base repo since June 26, 2010 (Ben Gras). .LI Somewhat apathetic, still using a version that is more than four years old. .LE .LI "MacOS X" .BL .LI An mdocml package exists since September 5, 2010. .LI Unfortunately, it seems abandoned. .LE .LI "Cygwin" .BL .LI An mdocml package exists since December 12, 2012. .LI Updated to 1.12.2 on November 11, 2013 (Yaakov Selkowitz). .LE .LE .GPE_TIME 120 NEW . .GPE_NEXT "Linux" "7.5:39" .SUBTITLE "Status in Linux distributions" .sp -1.5v .BVL 1c .LI "Alpine Linux" .BL .LI A testing aport exists since July 6, 2010 (Natanael Copa). .LI The aport moved from testing to main on June 12, 2011 (Natanael Copa). .LI Updated to 1.12.4 on August 28, 2014 (Peter Bui). .LI Potential interest to use mandoc as an alternative to groff plus man-db. .LE .LE .GPE_MULB 12c 1v .BVL 1c .LI "Arch Linux" .BL .LI An mdocml package exists since .br October 3, 2010 (Markus M. May). .LI Updated to 1.12.3 on April 17, 2014 .br and to 1.13.1 on August 17, 2014 .br (new maintainer Jesse Adams). .LE .LI "Slackware Linux" .BL .LI An mdocml SlackBuild exists since .br January 7, 2014 (D\('aniel L\('evai). .LI Updated to 1.13.1 .br on August 30, 2014 (D\('aniel L\('evai). .LE .LE .MULN .sp 1v .PSPIC Images/FlagstaffBluePenguin.eps (u;\n(.l-\n(.i)u .ce 4 .GPE_SM "Little Blue Penguin / Korora" .GPE_SM "(Eudyptula minor)" .GPE_SM "\(co 2009 Fir0002/Flagstaffotos" .GPE_SM "@wikimedia (CC)" .MULE .BVL 1c .LI "CentOS, Debian, Fedora, RedHat, SuSE, Ubuntu Linux" .BL .LI Unofficial mdocml packages exists since April 19, 2014 (Jesse Adams). .LE .LE .GPE_TIME 90 "BSDCan 2014 p. 28 (updated)" eurobsdcon2014-mandoc-slides/7/todo.roff010064400017500001750000000016631240641024700210700ustar00ischwarzeischwarze.GPE_NEXT "What shall we do in the future?" "7.1.2:37" .TITLE "Possible future directions" .sp -1v .BL .LI Replace the traditional BSD man(1) implementation with the mandoc one. .LI Switch the default output mode from .B \-Tascii to .B \-Tlocale . .LI Integrate preconv(1) into mandoc(1) for better UTF-8 handling. .LI Improve pod2mdoc(1) to better support perlpod(1) to mdoc(7) migration, .br in particular for the LibreSSL manuals. .LI Support automatic semantic enrichment of Perl manuals with pod2mdoc(1). .br I'm not yet sure this is practicable, it's just an idea so far. .LI Help man(7) to mdoc(7) migration with doclifter(1) and docbook2mdoc(1). .LI Unify parsers, allowing further improvement of low-level roff(7) support. .LE .sp -0.5v .PSPIC Images/AndrewBarclayMollymawk.eps 9.5c .ce .GPE_SM "Buller's Mollymawk / Toroa-teoteo (Thalassarche bulleri)\ \(co 2008 Andrew Barclay @flickr (CC)" .GPE_TIME 240 "BSDCan 2014 p. 39 (updated)' eurobsdcon2014-mandoc-slides/7/thanks.roff010064400017500001750000000173051240742263200214150ustar00ischwarzeischwarze.GPE_SECTION THANKS .GPE_NEXT "Who contributed?" .TITLE Thanks! .S -2 .sp -1v .BVL 1c .LI "Kristaps Dzonsons (bsd.lv)" for writing mandoc .LI "J\(:org Sonnenberger (NetBSD)" for important code contributions and for hosting an excellent mandoc hackathon at BEC.de .LI "Franco Fichtner (DragonFly), Christos Zoulas, Tsugutomo Enami (NetBSD)" for code contributions .LI "Marc Espie (OpenBSD)" for OpenBSD ports integration and lots of important feedback .LI "Jason McIntyre (OpenBSD)" for excellently and tirelessly maintaining our manuals, for helping with countless bug reports, and for discussing countless questions regarding mdoc(7) .LI "Theo de Raadt (OpenBSD)" for inviting Kristaps and getting mandoc imported. (Otherwise, i might have missed it.) .br for ongoing encouragement, in particular to make OpenBSD developers and users our guinea pigs. (None complained, they seemed to enjoy it.) .LI "S\('ebastien Marie" for a man.cgi(8) security audit .LI "Thomas Klausner (NetBSD)" for NetBSD and pkgsrc porting work and lots of feedback and release testing .LI "Ulrich Sp\(:orlein (FreeBSD)" for FreeBSD porting and many bug reports .LE .S +2 .GPE_TIME 180 . .SK .TITLE Thanks! .S -2 .BVL 1c .LI "Werner Lemberg (GNU troff)" for tireless help with groff-mandoc synchronization .LI "Natanael Copa, Paul Onyschuk (Alpine), Jesse Adams (Arch),\ D\('aniel L\('evai (Slackware)" for porting mandoc(1) to Linux and providing feedback .LI "Garrett D'Amore, Yuri Pankov (IllumOS),\ Matthias Scheler (Solaris), Ben Gras (Minix 3)" for porting mandoc(1) to Non-BSD systems and providing feedback .LE .S +2 .GPE_MULB 15.8c 0v .S -2 .BVL 1c .LI "Anthony J. Bentley (OpenBSD)" for porting related software to OpenBSD and many bug reports .LI "Todd C. Miller (OpenBSD & sudo)" for feedback and multiple patches to the mdoc-to-man converter .LI "Jeremy Evans (OpenBSD)" for crucial help with SQLite database optimization .LI "Christian Weisgerber (OpenBSD)" for continuous work on mandoc issues in OpenBSD ports .LI "Stuart Henderson (OpenBSD)" for help with large numbers of porting issues .LI "Pascal Stumpf (OpenBSD)" for repeated help with difficult groff porting issues .LE .S +2 .MULN .PSPIC Images/MarkJoblingRobin.eps .ce 2 .GPE_SM "\h'-1.4c'Robin / Toutouwai (Petroica australis)" .GPE_SM "\h'-1.8c'\(co 2007 Mark Jobling @wikimedia (PD)" .MULE .GPE_TIME 120 . .SK .TITLE Thanks! .S -2 For bug reports and useful suggestions and discussions: .P Alexander Bluhm, Antoine Jacoutot, Bob Beck, Brad Smith, Bret Lambert, Brian Callahan, Bryan Steele, Daniel Dickman, David Coppa, David Gwynne, Doug Hogan, Edd Barrett, Florian Obser, Giovanni Becchis, Gleydson Soares, Henning Brauer, Ian Darwin, Igor Sobrado, Janne Johansson, Jasper Lievisse Adriaanse, J\('er\('emie Courr\(`eges-Anglas, Jonathan Gray, Juan\ Francisco Cantero Hurtado, Kenji Aoyama, Kenneth R. Westerback, Kurt Miller, Landry\ Breuil, Martin Pieuchot, Matthew Dempsky, Matthieu Herrb, Matthias Kilian, Miod Vallat, Nicholas Marriott, Nick Holland, Nigel Taylor, Okan Demirmen, Paul Irofti, Paul de Weerd, Peter Hessler, Philip Guenther, Remi Pointel, Reyk Fl\(:oter, Stefan Sperling, Ted Unangst, Thordur Bjoernsson, Todd T. Fries, Vadim Zhukov (OpenBSD) .P David Holland, Nicolas Joly, Abhinav Upadhyay, Havard Eidnes, Jonathan Perkin (NetBSD), .br Antonio Huete Jimenez, Sascha Wildner (DragonFly), David Hill (Bitrig), .br Michael Dexter (bsd.lv), Carsten Kunze (Heirloom Doctools), .P Chris Bennett, Chris Hettrick, David Levine, Dmitrij D. Czarkoff, Fabian Raetz, Frantisek\ Holop, Guy Harris, Igor Zinovik, James Jerkins, Jan Stary, J\(:orn Clausen, Justin\ Haynes, Marcus Merighi, Maxim Belooussov, Michel Jansens, Mike Small, Mikolaj Kucharski, Ryan Flannery, Steffen Nurpmeso, Tim van der Molen, Tristan Le Guern, Will Backman .S +2 .GPE_TIME 60 . .GPE_NEXT "Where did the images come from?" .SUBTITLE "Thank you for sharing your pictures!" .sp -0.8v .S -9 .DS http://www.flickr.com/photos/tomkoadam/4778126822\ Adam Tomk\('o: Csik\('o \(en Foal (by-nc-nd) http://2014.eurobsdcon.org/wp-content/uploads/2014/06/BSDSofiaForWeb.png\ Alica Dimitrova: Sofia BSD Mascot https://www.flickr.com/photos/whereisbrent/461055143\ Brent Barrett: Kea juvenile (by-nc-nd) http://www.columbia.edu/cu/computinghistory/1965.html\ Columbia University: IBM 7094 (with permission) Courtesy of University Archives, Columbia University in the City of New York http://cm.bell-labs.com/who/dmr/picture.html\ Bell Labs: PDP-11 (with permission) Reprinted with permission of Alcatel-Lucent USA Inc. http://www.mckusick.com/beastie/shirts/bsdunix.html\ USENIX: 4.2BSD Beastie https://www.flickr.com/photos/29954808@N00/1300190844\ 57Andrew: Rock Wren (by) https://www.flickr.com/photos/docnz/8528275645\ NZ DOC: Kakapo (by-nc-sa) http://commons.wikimedia.org/wiki/File:StGeorgeRotundaSofia.JPG\ Preslav: Rotonda Sveti Georgi, Sophia (pd) http://www.flickr.com/photos/70058529@N00/5169255238\ Mihal Orela: Central Mineral Baths, Sofia (by) http://commons.wikimedia.org/wiki/File:Sofia_University_panorama_2.jpg\ Plamen Agov: Sofia University (by-sa) studiolemontree.com http://commons.wikimedia.org/wiki/File:NDK_Sofia_2012_PD_06.jpg\ Bin im Garten: National Palace of Culture, Sofia (by-sa) http://www.flickr.com/photos/podoboq/75568649\ Todor Bozhinov: Vitosha 2290m (by) http://commons.wikimedia.org/wiki/File:Tumba_Belasica_IMG_7972.jpg\ Deyan Vasilev: Tumba 1880m, Belasica (by-sa) https://www.flickr.com/photos/everexplore/8572686541\ Kiril Rusev: Kutelo 2908m and Vihren 2914m, Pirin (by-nc-nd) http://commons.wikimedia.org/wiki/File:Botev_Peak.jpg\ Gerovitus91: Botev 2376m, Stara Planina (by-sa) https://www.flickr.com/photos/tom-margie/2070704728\ Tom Margie (by-sa): still of Marty Feldman as Igor\ from \(oqYoung Frankenstein\(cq; fair use to illustrate the inspiration for the name of the program http://commons.wikimedia.org/wiki/File:Maliovitsa_54072.jpg\ Stelian Kasabov: Maljovitsa 2729m, Rila (pd) http://commons.wikimedia.org/wiki/File:Moa_mock_hunt.jpg\ Augustus Hamilton: Moa \(co expired https://www.flickr.com/photos/eastsidephil/4452171897\ Phil Davis: Squirrel digging (by-nc-sa) http://commons.wikimedia.org/wiki/File:Tokoeka.jpg\ Glen Fergus: Southern Kiwi (by-sa) http://commons.wikimedia.org/wiki/File:Silvereye.jpg\ J. J. Harrison: Silvereye (by-sa) http://commons.wikimedia.org/wiki/File:Nz_boobook.JPG\ Aviceda: Morepork (by-sa) https://www.flickr.com/photos/sidm/6681523917\ Sid Mosdell: Bellbird (by) https://www.flickr.com/photos/13564559@N06/1382926708\ mattyhike: Musala 2925m, Rila (by-nc-sa) http://www.flickr.com/photos/gazzat/3495392530\ Gary Tanner: Foals Just Wanna Have Fun (by-na-sa) http://commons.wikimedia.org/wiki/File:Red_fox_kit_2_%28Vulpes_vulpes%29.jpg\ Charlesjsharp: Red fox kit (by-sa) http://www.flickr.com/photos/66176388@N00/3436935367\ Mark Robinson: A Youngster on the Quantocks (by-nc) http://www.flickr.com/photos/kristavandervoorden/4737488285\ Krista van der Voorden: New Forest Foal (CC) http://www.flickr.com/photos/tambako/3578468294\ Tambako: Very young zebra (by-nd) http://www.flickr.com/photos/tiny_packages/5045038219\ tiny_packages: On the road (by-nc-nd) http://www.flickr.com/photos/jimmy-jay/4672901414\ Jeff Burcher: Horse Fly Portrait (by-nc-nd) https://www.flickr.com/photos/curiouskiwi/566823278\ Brenda Anderson: Fantail (by-nc-sa) https://www.flickr.com/photos/sidm/5225410158\ Sid Mosdell: Red-crested parakeet (by) http://commons.wikimedia.org/wiki/File:Little_Penguin_Feb09.jpg\ Fir0002/Flagstaffotos: Little Penguin (by-nc) https://www.flickr.com/photos/electropod/2817879475\ Andrew Barclay: Buller's Mollymawk (by-nc-nd) http://commons.wikimedia.org/wiki/File:070308_Stewart_Island_robin_on_Ulva.jpg\ Mark Jobling: NZ Robin (pd) .DE .S +9 .GPE_TIME 60 .ds gpe_next What would you like to ask? ¡®Yes, sir. I felt sure you understood that. She said she had told you.¡¯ "Why, eh,--I--I don't know that my movements need have anything to do with his. Yours, of course,--" "Ah, but if it saved your life!" "No, I'm not," grumbled the Doctor, "I've had enough of this wild-goose chase. And besides, it's nearly dinner time." "I am coming to that," Lawrence said, lighting a fresh cigarette. "As soon as Bruce was in trouble and the plot began to reel off I saw that it was mine. Of course there were large varyings in the details, but the scheme was mine. It was even laid on the same spot as my skeleton story. When I grasped that, I knew quite well that somebody must have stolen my plot." Judy In a coach-house, through which we passed on our way to see the prince's favourite horses with the state carriages¡ªquite commonplace and comfortable, and made at Palitana¡ªwas a chigram,[Pg 68] off which its silk cover was lifted; it was painted bright red and spangled with twinkling copper nails. This carriage, which is hermetically closed when the Ranee goes out in it, was lined with cloth-of-gold patterned with Gohel Sheri's initials within a horseshoe: a little hand-glass on one of the cushions, two boxes of chased silver, the curtains and hangings redolent of otto of roses. "Are you certain of it? You have seen so very little of him, and you may be mistaken." "And your wife?" "I drawed on my man's bundle o' wood," said Gid, "and then dropped a little, so's to git him where he was biggest and make sure o' him." HoME²¨¶àÒ°½áÒÂ×óÏßÊÓƵ ENTER NUMBET 0016kmjytf.com.cn
jdbianli.net.cn
okpktg.org.cn
www.vrgongyi.com.cn
qinghaiu.com.cn
needo.com.cn
www.qynytech.com.cn
www.nbfxj.net.cn
xerpdd.com.cn
www.wzchain.com.cn
欧美西方美女艺术图片 美女掰b图片 外国操逼成人片 肏屄蓝魔mp5官网 骚穴骚影网址 藤冲有关的电视剧 偷拍包厢内少男少女激情狂欢 大中华色露脸对话 黄片俄罗斯大学校园 久久炮图 类似狠狠鲁的网站 台湾大佬自拍偷拍网 人于兽性爱小说 美女上厕所刚出炉图 来插妹妹的小穴 美红换交 丝袜女女舔足 性爱换妻乱伦故事 女同性恋热吻优酷视频 苍井空裸阴毛 日本美女百濑图片 成人毛片快播高清影视 宫藤新一的性福生活 成人小妹 少女金频双艳 人与shuo 武汉教室做爱吉吉 人体艺术黑木耳西西 射极品空姐超碰 骚女自慰照片 江西公安局政委用枪逼儿媳妇通奸 浅川花里子 粉嫩逼贴图 一进大门观四方 诱奷表妹 和大姨子肏屄之续 日本 大胆人体艺术图片 松岛枫 中国女裸名单 美女露体没有马赛克 国产强奸乱伦加电影yingyinxianfeng 熟女人妻15p 诱奸 少妇 小说 天使的眼泪黄色群 伦理 偷拍 皮皮 骚女浪妇乱伦爱爱 幼幼性交比赛 魔王av亚洲无码bt 就要在线撸电影站 快播欧美荡妇聚会 影音先锋韩国女主 亚洲 性交图 看黄片不用要播放器 猪猪影院百度影音艺术片 人性交电影 妹妹看黄色片 浙江真实乱伦迅雷 一个最真实 的我 一个 的我 的我 歌曲 成人爱爱在线观看 色妹妹天天撸 插妹妹成人电影院在线观看 风间由美熟女人妻黑丝商务交会种子 男性大鸡巴被操的故事 人之初性本善 致橡树原文 神经系统体格检查 狠狠撸操干妈图片大全 中国成人电影小说 日姥姥性爱淫乱三从四德群交30p 爱爱jj发综合网 黑木香一经典番号 黄蓉与刘老汉 大黑鸡大吧操妈妈 印尼大胆人体艺术 草别人媳妇 人体艺体肉欲 互联网jiqingwuyue 白虎穴尿尿艺术图片 操操淫乱穴 寡妇自拍 三级色逼一片 林心如两腿分开 人与动物三客优 金伟哥vga说明书 日本av女优馒头逼图片 十九摸 儿子和母亲激情性交 有快播可以上的色网址 幼幼色色 ribenchengrenxiaoshuo 外国性爱网站 欧美美女人穴 性爱小说撸啊撸 呕美操逼图 女人的屄照片 人体艺体阴部插图片 百度云照烧铁板 我的八年性情史 淫香淫色插逼图 有黄的的qq号 欧美色亲片 zuixinmuziluanlunxiaoshuohetupian 杜比影院最佳座位 白雪公主摸乳干 美女露屄毛的图片 绫川まどか在线先锋 影音先锋操大奶妹 手机动漫成人电影网 强奸女护士 亚洲陈丽佳人体艺术 欧美经典七夕电影 WWWANGOULECOM 我和村嫂乱伦 母子通奸网 亚州色图就射 www777影音先锋 邓紫棋图片亚洲色图偷拍自拍 白嫩美女做爱爽图36p 瑶瑶的淫叫声 大树梨纱 人体私处大胆艺术图 母子插逼视频 母子淫水 狠狠干五色天 换妻17p 性之图吧偷拍自拍亚洲色图 激情性爱动漫欧美 WWW53AVCOM 启东操逼 艳母峰臀 欧美激情裸体艺术图片 激情明星狠狠碰 欧美强奸少女图 孟十朵 妻子玲儿 黑大炮群交内射白虎视频 西西人体艺术大胆人体艺术亚洲 白领穿丝被干视频 亚洲电影第10 归乡义母种子 骚丝袜老师 性爱亚洲色图大鸡巴 长谷川美红母 2014uuucom 神马影院未来电影在线 强奸少妇图片乱伦小说 我与妈妈做爱抽插操逼 ss5678 美丽的丝袜老师妈妈4 樱井知香裸体照 摸女人大胸图片 丁香社操逼 操美女av 久久热无码在线视频 去去去电影 女性尿道口真人版图片无衣 liaozaiyantan成人免费电影网站 超碰视频网友自拍第一页 色波波影院 迅雷下载 诱色天使香香裤高腰款 熟妇张柏芝丝袜 2015最新操 酒鬼电影院会员 秋露伦理Av 咪咪色色老师小说 i嘿片网 AV换妻电影 风间由美club 奶子大骚Pmsewuyecom 自拍爱色综合社区 手机看片操女优 av丝袜教师手机天堂 16668伪C0m 花俏小姨子mp4 久久撸久久肏开心五月 搜索sexinsexnet 厨房干同学妈妈的屁眼wwwwanren8netmwanren8net 日本小金井 美国十次啦老熟女 www色色网络com 天堂网妞赶 插蝴蝶逼 青青3p luanlun爱 小姐的的性感生活作爱片 激情短篇小学 牛牛超碰免费公开在线视频 日夜色先锋资源站 在线网站AV黑人wwwgzyunhecom 手机av受美国法律保护 性感老师校园春色 天天啪夜夜操www9eyycom 洪爷小说幼女交换 美女洞毛电影 雪白的古典武侠 三级片三级片的坏的视频播放 小说专区乱伦小说目录99 色第四色wwwav565com色就是色 舔岳母的小穴 肥佬能用的三级片网站 淫荡的肉弹美女教师 熟女香蕉无a在线视频 美女操逼黄色大片 www1111r80s 欧美色图迷人的骚女15P 哥哥干av成人社区男人天堂 武藤蓝av 搜索炼狱岛 精液降头 偷拍女厕所自慰图片 xxoo成人影院熟女 freefronvideos人母 卡通图片另类变态 春药潮吹痉挛视频 2017最新www超碰com 最新kkbokk 欧美露大乳图 激情电影乱伦小说 邻家丰满少妇 绑架调教性感丝袜性奴女 风流情哥哥网站 激情小说加多撸 欧美性虐哥哥射 变态淫荡 seyuyue 人体穴鲍图 伊人在线视频变身6 中国十大禁书黄小说 国产自拍秀mp4 性交口交天天撸 裸体摄影优果网 少妇人妻自拍图区 久草在线新时代3wwwczyzxcnzxzy8com 最大胆一千美女 大几把骚逼 全国最大三级图文 干了校长的骚穴 与妻侄女 户田惠梨香av片 家庭乱伦之人妻 淫贱孝姨 干美女狗趴 变态孕妇母乳片 sss480 偷拍穴毛 yazhouxingjiaosetu 明日花绮罗京都不伦妻 se牛牛视频网址 婶婶的原味内内 偷拍自拍做爱操逼 天天瑟瑟天天撸 蕾丝兔宝宝图片 华为网盘饭岛爱 天天鲁鲁天天在线 岳母与女婿性爱故事 2016年的小萝莉网站 狐狸色成人AV网站 18岁女主播直播自慰 qinglouscom 农夫激情基地 免费小萝莉自慰在线直播 wwwmmtt11me 性交透明内衣美女乳头无遮挡 亚州av潮吹视频 高跟熟女性奴 淫秽黄色啪啪手机视频 幼同志 怡红院更新前的主页 青青草肛交灌肠视频在线播放 搜索100avcom 老熟女下一篇7p 国语对白AV在线观看wwwyaob111com 成人动漫在线免费 11ppdd页面访问升级 189df、com wwwsesoucom 舞会电影台湾 www550ai30in 伊人情人网综合wwwggsao58info 都市淫秽 朋友妻子穿着丝袜让我舔 激情网址五月天 奶大妞女 兽皇英国 老熟女喷水小说 淫淫撸 偷拍影音先锋电影网 网上聊操逼 www路ppp7cnm 色色成人Cy视频 性吧春暖花开性吧有你旧版 丝袜制服人妻交换 鬼父第十七集番号 映像av加勒比先锋影音 wwwtutu10cnM 欧美乱伦18p 大香蕉超 国产看片点我 日本女穴 阿v手机天堂 稻田淫 wwwyouijzzsmcnm 我的办公室老婆三邦年 郑重声明我们立足于52avav xingnuchuanqi 黄色电影露阴毛 黄色录像番金莲 AV91 影音先锋强奸影片 亚洲在线a手机 曰本女优在线www5sdlcom 帮帮鲁色老汉 在线成人小视频下载 黄色网站都有那些 大胆人体露阴艺术 浅田美姬 草榴免费视频 捷克??机 丝袜美女被性侵 日日性 丝袜人体艺术偷拍 凹凸视频在线av 情欲超市小说 西西里大胆艺 黄片免费网址 东方a∨在线亚州色图狠狠撸 苍井空超短裙丝袜诱惑图片 奇米成人影视色和尚、色尼姑 ckck爱情电影 恋爱记录短片分享 局长成长史686 AV成人播放器免费的 纯洁的玛利亚邪恶漫画 五月激情综合狠狠色 wwwbbb552cm 性插网页 美女丝袜撸撸五月天 色色泡泡影院 一部女生被插jj的完整黄片 wwwadcrrr222con 秋霞伦理片在线播放 教室调教老师 亚洲色图日本AV 很很艹 日骚妇内射在线视频观看 ya亚洲麒麟色影影院 qqb66666 亚洲色图欧美色图美腿丝袜 曰一日 农村少妇电影magnet 移动成人你射精 20158韩国女演员激情视频合集 酒店小姐裸体艺术照 足浴小姐做爱过程 av女教师自慰动态图 AV影音先锋影院 123红色播放 女友自拍偷拍刺激 wwwseebimei 123CTCTCOM 婷婷xx youjuzz小说专区 一级黄色wangzhan 男人体摄影 裸体两性 欧美精品超碰 强奸小村花千骨 幼少女肏屄视频18 五月婷婷婷婷五月丁香 色魔在线 国产父女乱伦小说 KTKX089 www454HUcom 在线手机播放器 偷拍自拍32 成人激情图片，电影mmmnn7777 ww777rvvom WWW9itKcom 美国名模啪啪啪 用力的操狠狠的干 小浪穴妹妹亚洲色图 525zzzcom 乱伦妈妈15p 唐伯虎点秋香不是三级片 最大色牛牛 欧美色kuaibo 手机在线tokyo 欧美幼女网mp4 760yycom 少妇干净迷人鲍优优 绳艺magnet 身穿民族服饰的中国少数民族漂亮美女大胆人体艺术7国内 www47escomxz34 Www2222magnet 色偷怕自拍视频 丁香五月天拍拍播放` 青苹果影院噜噜妈妈 公然妄想露出在线 图片区偷窥自拍亚洲色图欧美色图动漫图片美腿丝袜清纯唯美乱伦图区电 黄色三级片77天天撸 美国女孩成人网站 东京热亚洲色色 超碰av大帝在线视频 西瓜成人资源网 一级片城年5 孝姨大阴唇 pp529com 青青色草在线 504hu迅雷下载 殴州1314 母子乱论视频 微信自拍成人视频在线观看 www44cim 东方av官方 297Pmp4 骚av老师 小明看看成人永久免费视频在钱imgcctuocom 越南人体艺术露鲍 两个女人用道具做爱 影音先锋制服丝袜偷拍 爱搞搞爱撸撸爱色堂 闹洞房就去干 男根的诱惑系列 樱井亚莉偷拍自拍 色dogcom 里中结衣在线观看 特大鸡巴碰上大波霸 躶体狂插相片 熟女撒尿视频 国产成人在线视频网站 武汉18中教师门 刘亦菲阴道毛多吗 操b网址大全 欧美性生活色图 母子尾交 图 操山村老大妈 淫母之穴 00后人体图片少女无毛掰开图片 6655人体艺术果果人体艺术波谷人体艺术 刘嘉大胆人体艺术 欧美色图 成人动漫第一页 淋浴做爱av 骚逼yaoyao 9115视频在线资源sss 黑屌做爱爽片 女优性交免费电影 欧美熟肥女图片 韩国女主播朴妮唛的黄色小说 撸哇哽播 在线自拍干幼女 高清晰自拍偷拍图色色网 去哦v大 欧美父女性爱 淫秽网站肥女视频 666亚洲无码 最新日韩乱伦小说网站 操少妇游戏 日本少妇11p图片 什么片好黄 多人合集9部 河合优衣ed2k 狠狠撸美女手掰穴图片 女儿交换乱轮 欧美妈妈和她的大屌儿子 富婆和年轻帅男性交 夫妻居家性爱自拍 色色偶性爱自拍 强奸模特小说 少年与熟妇爱图 体操美女之性生活 色骚逼在线高清播放 www1314xxx 韩国三级片一对男女在大学教师xxoo后来女的怀孕了男女结婚后女的跑了男的和 夫妻坐爱一级片 成人男女做爱视频 人体艺术图片绘狗网 入江辉美在线电影 鲁av影院 动漫同志片 风间由美爱爱网站 乱伦3p生活 最美妙的骚逼 王梦溪迅雷种子下载 我姐尻屁片 亚洲色图人妻p 日本人体艺术波之轩 偷拍黄色照片 汤加l丽裸照 伦理片日本家庭教师 操逼撸撸撸吧影院 WWW_BB152_COM 保险知识 左边杨丞琳 女人淫乱图 穿挺屄裤子的图片 色色公公与好儿媳 苍井空完全服从 色姐姐乱依 人妻乱伦星野绫香 熟女的角色扮演性爱快播 快播奸少女阴道电影 都市激情撸情 女人小穴很很日 狠狠肏老婆 亚欧人体摄影 中华医药艾叶作用在线视频 美女粉乳头10p 俩根大吊插一个美眉 品色堂俺去也 l少女luluse 模逼图片 山下智久柚木提娜种子ed2k 桃色播播激情五月天 沙绪里与狗 橹二哥影院影视先锋 小说快播综合网 12306影院第一页 巨乳无码xfplay 萩原舞电影 学生逼逼电影 欧美群交欧美色图 操少妇的逼短片 韩国主播吉吉影音 影音先锋厕所偷拍片 欧美熟女系列 鹿鼎淫记 3p性感尤物内射她的小骚穴 国产强奸幼幼逼 屌配屄毛 美女做热爱性交口交 女主人的人体厕所 顶级黄色图片可看到阴道口 无码少妇在线色 美女吹萧爽吗 黄色网站是多少翱 妹妹视 人体模特毛婷人体艺术 佐藤爱理番号 开心宝贝色播网 大屌巨乳系列 重温陈冠希图片做爱 美女豪乳50p 黑网袜性爱 操熟女老师 日韩av逍遥社区 安装香港恋夜场秀 美女制服诱惑男女 亚洲人妻岛国线播放 色小说色图色电影 日韩美女映画网 成人动漫转帖区 www狠狠射c 露脸绝对领域 妻子地铁失身 淫老婆电影第一页 中文字幕都市激情家庭乱伦亚洲色图 日本美女特大胆裸体露逼 口工教师av 色色999偷拍自拍日韩美女 www968ddcnmagnet jjjhhh1com日本 老王社区lw78cc ed2kyounv 美女口交舔逼小说 类似古丽阁网站 帅男同的鸡鸡ed2k 少妇的小骚玩 av黄鳝自慰小说 经点乱系列 百度久久做爱视频 a狼电影网成人 干小嫩b10Pwwwneihan8com 原国产母子做爱乱伦 美国十四拉人体艺术 老公我要插深点快点啊 涩涩乱伦小说 波霸暴露 994yyccm 美国女人和动物zzzwww 后入式微拍 中国国模03150p 色色色乱伦熟女图片 欧美大胆嫩肉穴爽大片 这个经典的给你吧rr123win 老婆乱伦片 另类少妇AV 巨乳俏女医漫画 WWWSWWWMITAOCOM 糖糖激情操逼 男屁眼被曰小说 yinsezonghewang 爆操人妻熟女15P 福利脱衣麻将 久久热偷偷撸黑丝袜免费经典视频 电影三级mp4黄色电影 超级黑人巨屌操白妇 人妻偷拍自拍强奸 男男激情小说肉文 韩日女优大奶视频 杀神有声小说 有声性小说mp3mp3 天春色图片 春色龙 樱井莉亚口才 日本成人 求h网导航 h网游游戏 有没有免费的黄网 设置加www 开心网 五月天 的五月天 qvod东京热图片 东京热n0383.rmvb 皮皮看黄片 沙发看黄片 黄色小说短篇 大色鱼情迷 风月阁论坛 日韩色姐姐 色兔子成人 师傅搞综合 18人体艺术 amod在线 大M成人综合 我爱弟弟影院 给力QVOD色 最纯洁少女做爱 無双帝國谁有E谁有G adultbig影院 日日顺 久久爱 歪歪小说网 九型人格分析 分分操导航 2017 一本道va手机在线 youjizzⅹⅹx 婷影院 一楼一凤影院欧美首页 猫蛋蛋很黄 shenyifuli ssni 049bt下载 另类图片-色爱 汤姆影院atom55 五月丁香深爱基地 皮特成人影院 gay pornhub video chitu x77223 色色ev 客车偷拍图片大全 动漫av ftp 青青草免费线观综合网 兄嫁はいじっぱり认证补丁 人妻少妇视频系列 小林瞳电车痴汉代码 秋霞短片福利 青娱乐视频盛会 日韩成人午夜视屏 影音先锋 熟女系列 在线观看皇片你的懂的 原千岁全集协和影视 日本一级性交视频 日本人性交视频 又黄又色的影剧院 大型AV 好屌色狼 早乙女由依 最佳专辑 尹人影院大香蕉禄现 吉泽明步私处流出资源大 伦理战场 情欲影院云播 bestfornmc0m 搭讪 mgnet 玩农村小姑娘裂缝电子书 日本AⅤ无码在线观看 伦理聚合高请无码在线播放 b里香视频在线2白色爽 有个妮可舍宾怎么找她视频 妇女磁力下载 凹凸視頻免賛在線 caosaobi在线观看免费 东方影库300 wwwxyc123con ipz862在线观看 武则天一级全黄视频 迅雷下载 亚洲在线一区 丰满女人多毛 思思热在线色视频 噜死你们资源站 mum骑兵在线播放 欧美色图狠狠插 邪恶插阴口动态图 风月影院黄视频 黄片VX 厕所偷窥视频 ay电影院 wwwkp99 木村都那厕所无码 good电影神马小丢 黑人和中国人群交视频 色色网址在线 九月婷婷在线 久草在线首页老司机 500dh com福利 杀戮都市里番在线 电影天堂在线福利 淫色视频网 苍木玛娜教师链接 97人妻C○m piczz漫画 橘梨纱作品Bd播放 激情按摩胸部无码 yy6080最稳定的资源 shtv123 日本成人影片 magnet 里番姐弟的关系3 超级碰av公开在线 thzvip 草帽国产综合网 日本色木木 dv1456 老色哥第四色 亚洲av欧美av电影av视频 日日夜夜插天天插 桃花影院今日新鲜事 A片网主名字 大屁股啪啪无码高清视频 东方阿v视频在线最新 xxoo淫交视频 电击女神asia fox在线 东北可爱小骚妻又一次3p娇小身材力战大屌-9 扒开双腿拳交 给我来个娘们操逼的黄片黄片 日本黄色枧频 j鸡巴小視频 叛客与雷鬼高清 迅雷 下载 美女自慰流淫水 在线 人妻小悠福利在线 巨乳王瑞儿在线视频 啪啪肉捧往哪叉?视频 劲暴欧美 一本道 东京热 自拍 国产 无码 黑丝自拍做爱 538prom久久日逼 www骚逼 XXXWWWUUU 求个一本道的资源 杨幂醉酒视完正版视频在线观看 日本女用胸为客人性按摩影院 仲村里绪 影音先锋女主播视频网站 vtt944 国产自拍福利社视频 18v韩国主播 在线翘臀福利 校园多女一男类番号 微福利吃精 香坂里奈 热舞福利120 538porm在线插放视频 wwwtaosetvcom 日本三级天堂网无码 韩国歪歪漫画官网进入 欧美图片亚洲色理论电影 欧美AVmm625 爱色影分类 56popo体验区 www奔驰宝马成人网站 射丝袜足 在线影院 kanmitao1视频 巨乳女教师の诱惑电影 欧洲老女人肏屄 ygyg66怼粉逼 热带夜中文字幕mp4 洁泽明步 m3u8人妻 蛇精脸网红主播小兔兔现场啪啪大秀 mmavtv少妇 萝莉小妹妹av 免费做爱视频网站免费 AISS模特索菲 在线福利视频 多毛龟 66ffff视频 佐伯雪菜在线av先锋 51zhiyuan 播播影院免费A片 av5685 真人下体抽插下阴喷水视频 色喜 王丹 美女动态图张又黄又色 www,O3ⅩXX,Cm 国内在线自拍人人澡人人看 BT 冲田杏梨巨乳女教师の诱惑 神马影院午夜伦dy888mmm 大香蕉亚洲人妻小说 丝袜自慰视频在线观看 涩播音频 popo福利网盘2018 性污秽小视频 想上你日你视频 享悦国产在线 校园禁断介护 校花在浴池被强视频 香港十大禁片黄e 小苹果性交影院 老湿影院未成年人 Xxxxx161116骆驼祥子 熟女papa视频 亚州影院午夜-一 97jibayingyuan 色欲直播 处女中出视频 爱爱福利区 鸡巴操逼的黄片 500夜趣福利免费 亚州香焦视频 porn在线播放制服丝袜 91c仔内裤哥在线观看 wwwz9k6com 偷拍美女浴室伦理电影 4438x3全国最大情人网站 速看网在线观看 新妈妈 ftp 亚洲国际成人综合 4455qu类似的网站 水菜丽无码粪便av连接 wwwabc300wom 唐朝TV360 国产AV,亚洲AV 采桑洗浴中心 波多结野衣与无码观看 比比琼斯作品合集磁力 山谷两日 thunder 日本高清凌辱免费三级片 magnet 欧美虐性 av无码 中文字幕 迅雷 樱井步禁断介护在线 四房色播av 织田真子113在线观看 罗马狼窝影院 插进去拔出来综合网 台湾R级在线 SOD时间禁止器 s跳蛋调教视频 WANQUEYINGYUAN 超级碰夜色猫视频 成人日日夜拍拍 RCTD mp4 v ip eeusssvv 求手机能看哪种视频的网站 欧美激情第一页在线观看 俺去也看免费视频 视频小姐中出 三七影视成人福利播放器 伦理无料 日韩SM高清 赫敏被强奸视频 泄欲哥导航为什么看不了了 1啪啪啪视频app 色无极亚洲影院东京热 黄色福利1000 要要橹福利 乱伦1视频 岛田阳子拍了多少AV片 正在播放肛交视频 萝莉无码小视频 本田英里子MP4迅雷种子 厕所偷拍无修。 北京彪哥真皮大床激战学院派 苍井空在线毛钱 波波兔 磁力 操奶子视频 波多野结衣与狗激情直接视频 久久干视频 ftp 橹先生成人影片 色妻视频观看 暴力插美女屁眼视频 48号缚师绑美女 草榴影院女同 空姐不愿意拍视频被男友强干到高潮的视频 sskanzyz新资源 小岛南无码链接magnet 小草草大黄瓜在线观看 renrencaome 虐阴漫画 国产第一页天天拍 wwwsesw 优酷 解放军在巴黎 18禁自拍偷拍 韩国肛交视频播放 美女做爱磁力连接 捆绑天海翼 5xsq四虎 美国十次啦福利视频 射精丝袜的视频 美女被人舔阴帝视频 乱伦香蕉色视频 色狐免费无码电影 美国成人性爱电影 六月丁香手机在线观看 教练和学生作爱视频 加勒比在线视频网 强奸乱伦1 骑士美女AV视频 去火涩 成人av视 ed2k 婷婷基地色色网 五月婷综合官网 撸必撸 足交鸣人漫画 gvg567 黑丝FJ 菲菲去网站 如果电话亭 avi rhj-073 黄片日屄视频 shiwaizhipaizhao 偷偷撸电影院 手机看片永久免费在线观看国产频道 国产另类自拍亚洲 天堂国产手机a 自拍视频在线观看 teen萝莉 不打码木叶性处理医院 风月海棠空姐 3d hy工房 在线观看 femmina在线观看 陈冠希艳照1300张阿娇 黄色网站在线视频 黄色综合网站 好看的中文字幕色拍拍噜 哦哦弟弟 黄色A片直播 后人动态图 qplayer在线播放网址 www第四色 野战情线国产视频在线观看 偷拍自拍在线赌博 护士无码视频 鬼佬　在线　云播 桃乃木香奈在线三上悠亚在线 ipx247在线观看 天降艳福不是福绝版在线看 一本道0588视频 日本无码光谍区 尻屄AV 老太太h类在线视频 国产3P自拍偷拍 伦理视频黄片大全 91小青蛙红杏出墙3p 内藤幸恵 你懂的 国产在线观啪啪啪网站 国产自拍、欧美 呦呦禁处 福利国产成人强奸少女50集 玉狼影院 国产偷拍自拍中文对白在线 阴道内窥镜凌辱女友 嘿嘿嘿影院永久 可知子 无码 成人在线黄色电影 快播八戒网 我要干色和尚 大胸美女一级黄色毛片 日本绣惑电影 yingyinxianfeng ziyuang 露脸操白妹国语 日本女性爱视频在线观看 成人狂欢福利网 91偷拍视频在线观看 操同事的小女友爱剪辑 粗暴轮奸视频 国产自自拍永久免费 天天干b天天插 国产25P 凹凸视频线观看免费 不雅视频磁力链接下载 香蕉影院超频在线视频 新加坡人美国艳星口交视频 肛塞自慰视频 8338磁力链接 成人色色网美国av幼女 把鸡巴插入妈妈的阴道 24美图野战 我和老师做爱漫画 淫乱肛胶美女 日撸神 清纯漂亮的嫩妹女孩与男友在家激情做爱流出高清视频mp4 阿姨熟女丝袜 黑丝袜电影院 色图网大全 丝袜阿姨的淫荡生活 日本乱伦变态 熟妇性交视频女人色网站 1234qec0m 六年级学生屄 波谷桐原 爆操巨乳妈妈 阿v天堂2012关于苍井空的视频 淫秽的我 官场艳情纪莜竹 少妇性交图25p