From 5d8ca034508343ed1f183e6d2bb6e278c20c31d1 Mon Sep 17 00:00:00 2001 From: June McEnroe Date: Thu, 27 Sep 2018 16:50:25 -0400 Subject: Add "Writing mdoc" --- 002-writing-mdoc.7 | 138 +++++++++++++++++++++++++++++++++++++++++++++++++++++ Makefile | 1 + 2 files changed, 139 insertions(+) create mode 100644 002-writing-mdoc.7 diff --git a/002-writing-mdoc.7 b/002-writing-mdoc.7 new file mode 100644 index 00000000..92c2fc05 --- /dev/null +++ b/002-writing-mdoc.7 @@ -0,0 +1,138 @@ +.Dd September 27, 2018 +.Dt WRITING-MDOC 7 +.Os "Causal Agency" +. +.Sh NAME +.Nm Writing mdoc +.Nd semantic markup +. +.Sh DESCRIPTION +I recently learned how to write man pages +so that I could document +a bunch of little programs I've written. +Modern man pages are written in +.Xr mdoc 7 , +whose documentation is also available from +.Lk http://mandoc.bsd.lv . +. +.Pp +.Xr mdoc 7 +differs from many other markup languages +by providing +.Dq semantic markup +rather than just +.Dq physical markup. +What this means is that +the markup indicates what something is, +not how to format it. +For example, +the +.Ql \&Ar +macro is used to indicate +command-line arguments +rather than one of the macros +for bold, italic or underline. +This frees each author of having to choose +and enables consistent presentation +across different man pages. +. +.Pp +Another advantage of semantic markup +is that information can be extracted from it. +For example, +.Xr makewhatis 8 +can easily extract the name and short description +from each man page +thanks to the +.Ql \&Nm +and +.Ql \&Nd +macros. +I use the same information +to generate an Atom feed for these documents, +though in admittedly a much less robust way than +.Xr mandoc 1 . +. +.Pp +When it comes to actually writing +.Xr mdoc 7 , +it can take some getting used to. +The language is of +.Xr roff 7 +lineage +so its syntax is very particular. +Macros cannot appear inline, +but must start on new lines +beginning with +.Ql \&. . +Sentences should likewise +always start on a new line. +Since I'm in the habit of writing with +semantic line breaks, +I actually find these requirements +fit in well. +. +.Pp +The more frustrating syntax limitation to me +is the rule against empty lines. +Without them, +it can be quite difficult to edit a lengthy document. +Thankfully, +lines with only a +.Ql \&. +on them are allowed, +but this still causes visual noise. +To alleviate that, +I have a +.Xr vim 1 +syntax file for +.Xr mdoc 7 +which conceals the lone dots: +. +.Bd -literal -offset indent +if exists("b:current_syntax") + finish +endif + +runtime! syntax/nroff.vim +unlet! b:current_syntax + +setlocal sections+=ShSs +syntax match mdocBlank /^\\.$/ conceal +setlocal conceallevel=2 + +let b:current_syntax = "mdoc" +.Ed +. +.Pp +It also adds the +.Xr mdoc 7 +section header and subsection header macros to the +.Cm sections +option to make +.Xr vim 1 Ap s +.Ic { +and +.Ic } +motions +aware of them. +. +.Pp +With that, +I've found writing man pages pleasant and rewarding. +I've started writing other documents with +.Xr mdoc 7 +as well, +as you can see here. +. +.Sh SEE ALSO +.Lk http://rhodesmill.org/brandon/2012/one-sentence-per-line/ "Semantic Linefeeds" +. +.Sh AUTHORS +.An June Aq Mt june@causal.agency +. +.Pp +This document is produced from +.Xr mdoc 7 +source available from +.Lk https://code.causal.agency/june/text.causal.agency "Code Toilet" diff --git a/Makefile b/Makefile index d74df97c..90d550d1 100644 --- a/Makefile +++ b/Makefile @@ -1,6 +1,7 @@ WEBROOT = /usr/local/www/text.causal.agency TXTS += 001-make.txt +TXTS += 002-writing-mdoc.txt all: $(TXTS) -- cgit 1.4.1 logheader'>2022-03-24Skip matches with ident chars on either sideJune McEnroe This fixes, for example, where the link gets placed on static regex_t regex(const char *pattern, int flags) in title.c. 2022-03-24Add The Invisible Life of Addie LaRueJune McEnroe So good, but so long. Reminded me of The Ten Thousand Doors of January at the beginning, and more of that N. K. Jemisin series about gods later. I like this interacting with gods and becoming something like one sort of thing. God, it took me a whole month (more?) to read and this is only my third book of the year :( I need some more novellas to read, but the other books I have from the library currently are also thick. 2022-03-22Source ~/.profile.local if it existsJune McEnroe 2022-03-18Publish "Addendum 2021"June McEnroe 2022-03-16Remove wcwidth portJune McEnroe DYLD_FORCE_FLAT_NAMESPACE no longer exists in macOS 12 so this approach doesn't work anymore. Moved to <https://git.causal.agency/jorts/tree/wcwidth> and compiled into <https://git.causal.agency/jorts/tree/ncurses>. 2022-03-16Remove -j4 from ./PlanJune McEnroe Plan learned to set this automatically! 2022-03-15Rewrite Linux install.sh for DebianJune McEnroe 2022-03-15Remove dashJune McEnroe