#OpenBSD 7.7 has been released (#BSD / #NetBSD / #386BSD / #Unix / #LibreSSL / #OpenSSH / #OpenBGPD / #OpenSMTPD / #OpenNTPD / #OpenIKED / #rpkiClient / #mandoc) https://openbsd.org/

Has anyone talked to Ingo S of #mandoc maintenance fame lately?

Please DM if you have news.

#OpenBSD #NetBSD #FreeBSD #macOS

@ollien In a couple of days

https://man.freebsd.org/cgi/man.cgi?query=sync&manpath=FreeBSD+15.0-CURRENT

should contain the changes but for now I published the HTML render of the manual page here:

https://people.freebsd.org/~0mp/sync.html

(It was generated with `mandoc -T html bin/sync/sync.8 > /tmp/sync.html`)

#documentation #freebsd #sync #foss #opensource #mandoc #mdoc

#OpenBSD 7.5 has been released (#BSD / #NetBSD / #386BSD / #Unix / #LibreSSL / #OpenSSH / #OpenBGPD / #OpenSMTPD / #OpenNTPD / #OpenIKED / #rpkiClient / #mandoc) https://openbsd.org/

@mos_8502 Probably because (even 😏) tex is more readable (and, of course, more verbose) 😉

The only thing that still forces you to use (a limited subset of) #roff (with some macro package) is authoring manpages that should work "everywhere" (read, systems without #mandoc support) 😉

Of course, still an interesting thing to cover. I guess "power users" (having to typeset stuff a lot) would actually like the pretty terse syntax.

@wwwgem nroff user, mostly, not GNU gnroff.

I prefer nroff with -mdoc when the primary end result does not need pictures or where plaintext availability has high value (e.g. manpages, but also other systems documentation). This is very nice to write, much nicer than Tₑχ/LᴬTᴇΧ or -man, and semantic markup.

Then GNU groff can be used to provide an additional PDF which is at least somewhat legible, and I do my own HTML conversation from the plaintext output, but mdocml (now called mandoc) can be used to create somewhat good HTML if you stick to -mdoc commands instead of using nroff primitives. (Which I tend to not do.)

I very much dislike how the GNU g{,n}roff macropackages have changed with the last release. The MirBSD nroff macropackages, specifically -mdoc, work well with GNU g{,n}roff and mostly avoid the pain. (Writing \- and a font hack were still needed.)

nroff with -man is just ugly and awful, stay away from it.

nroff with -ms (+), -me (ref), etc. is also possible, but I found -mdoc more modern and therefore less buggy.

I haven’t yet used neqn (doc, guide) or pic and only a little tbl (doc) (mostly, the native -mdoc tables suffice); AT&T nroff does not have a working pic and it doesn’t transfer to plaintext output well anyway.

I use Tₑχ/LᴬTᴇΧ when the end result primarily must be a PDF with pretty pictures (such as the installation manual of a software at $dayjob we handed to paying customers) or for more programmability. Though copy/paste from those PDFs is so bonkers I patched lstlisting to also dump the listings to a .lst file we provide along, so the admin can copy/paste the commands, examples and config files from there.

(I’ve never used $…$ math mode. I’m not in academics ☻)

I’ve pimped both (have my own Tₑχ/LᴬTᴇΧ styles/class and packages, and tweaked my groff fonts (example) and bugfixed the raw roff that implements the macros). I use both depending on where.

For my Mu͒seScore workshop, I even have a link list (source) written in a roff-like format that I convert to both Tₑχ/LᴬTᴇΧ (for PDF output) and HTML (for the website) using a Korn shell script, so much I like the format and structure.

Otherwise I’m somewhat a fan of plaintext (with UTF-8 line drawing, etc.) but not rST or md, and a large fan of just handwriting XHTML/1.1 snippets that can be included in webpages. (This ofc doesn’t transfer well to PDF.)

#nroff #groff #tex #latex #mdoc #mdocml #mandoc #mksh

another classic god fucking damn #mandoc moment

Fun fact tags in manual pages work better when running
mandoc -a draftmanpage.8
as opposed to
mandoc draftmanpage.8 |less

:) #OpenBSD #nsh #Mdoc7 #Mandoc

reading #contracts is more exhausting than writing a #mandoc for the first time;... annalogy for contract negotiation in mandoc is mandoc -Tlint ...rince n repeat.....

#mandoc -Tlint nsh.1 has exploded (and im not saying it is due to name on the file ... (more like the contents :)
Starting at the top and working down ...

Do people realise how long it takes to write manuals
...
it takes a while ...
it kind of sucks when you find a better formatted manpage and you know in your heart and soul that you got to go back and re do all your mandoc tags ... perfection is a moving target #mandoc #OpenBSD #nsh

Dear #OpenBSD folks, who should I contact with a patch for #mandoc?

#English #UNIX Question:

1) It is printed to the standard error
or
2) It is printed in the standard error

#BSD #man #manual #mandoc #doc

I've decided to publish a little #CLI I use to auto-reload previews of manual pages when I work on #FreeBSD documentation.

https://github.com/0mp/mantra

It is now available in the FreeBSD #ports collection: https://freshports.org/textproc/mantra

#opensource #mandoc #openbsd #netbsd

Ok, I'm pretty sure cawf 4.10 is the last version of cawf. It's from 1996. The minix version I was playing with earlier is either 4.8 or 4.9.

(groff released in '97, pretty much made cawf pointless)

It was an easy port to RISC OS. I have a little bit of packaging to do yet but it's basically done.

Unfortunately it still can't deal with mandoc or mdoc manpages.

#riscos #cawf #groff #nroff #manpages #mandoc #mdoc

If the newer version of cawf supports mandoc macros it might be worth porting.
#cawf #manpages #mandoc

Worked with mandoc(1) for the first time, and I was impressed by how well designed it is. Manpage can now be converted to html in the #hakyll building pipeline:

https://meli.delivery/documentation.html

#mandoc

My ideal solution would be a plain text format that's easy to parse for both humans and machines with a #minikanren / #prolog like language to query and index it.

#mandoc is nice, but apropos(1) and mdoc(7) have limits to their flexibility.

https://www.youtube.com/watch?v=jwfN7S1-fRA a video of Ingo' Schwartze'#s Presentation on Documentation and LibreSSL in @eurobsdcon 2018, Ingo Demonstrates as always his keen attention to detail. Im just sorry that I didnt arrive in time for the start of the Presentation #RUNBSD #mandoc #LibreSSL