3 ms·

OpenBSD manpages are written in a semantic format, -mdoc, that readily converts to HTML with inter‐ and intra‐document hyperlinks, and facilitates searching and

by anjbe 7y ago

OpenBSD manpages are written in a semantic format, -mdoc, that readily converts to HTML with inter‐ and intra‐document hyperlinks, and facilitates searching and hyperlinking even from within the terminal (via more(1)’s tags support).

Crinus 7y ago
I know, but writing a coherent manual is a different task than writing a short reference page, especially if you want to include more content than just a reference (e.g. user guides or tutorial sections) and writing text that assumes inline hyperlinking is always available. Note that this isn't about it being technically impossible, you can certainly do it, but it isn't the right tool for the job - a dedicated manual reader provides a better UX here (and the failure of GNU info to provide a user friendly experience is, IMO, the reason manpages are abused so much in Linux).
- JdeBP 7y ago
  You're talking about the grossly-misnamed (since large portions of it do not contain any questions) OpenBSD FAQ, which is where guide and tutorial stuff is to be found. BSDs (and some others) come with variously-named Handbooks. OpenBSD has the aforementioned. FreeBSD has a Handbook. So do DragonFly BSD, NetBSD, and others. They are distinct from the user manuals, which are the reference doco. They are, indeed, hyperlinked. Already. * OpenBSD FAQ: http://openbsd.org/faq/index.html http://openbsd.org/faq/index.html * NetBSD Guide: https://netbsd.org/docs/guide/en/ https://netbsd.org/docs/guide/en/ * FreeBSD Handbook: https://freebsd.org/doc/handbook/book.html https://freebsd.org/doc/handbook/book.html * DragonFly BSD Handbook: https://www.dragonflybsd.org/docs/handbook/ https://www.dragonflybsd.org/docs/handbook/ * GhostBSD Handbook: https://wiki.ghostbsd.org/index.php/GhostBSD_User_Handbook https://wiki.ghostbsd.org/index.php/GhostBSD_User_Handbook * MicroBSD Handbook: http://damnsmallbsd.org/MicroBSD/handbook/ http://damnsmallbsd.org/MicroBSD/handbook/ * OpenIndiana Hipster Handbook: http://docs.openindiana.org/handbook/getting-started/ http://docs.openindiana.org/handbook/getting-started/ * old TrueOS User Guide: https://trueos.org/handbook/trueos.html https://trueos.org/handbook/trueos.html
  - Crinus 7y ago
    I'm not talking about any specific guides or manuals, but yes the OpenBSD FAQ, FreeBSD Handbook, etc are the sort of manuals i am talking about. But those are not made in manpage format and at least the OpenBSD FAQ HTML pages seem to be edited by hand. And since those are in HTML (at least the OpenBSD one, i didn't look into the others) they lack the indexing and ebook-like reading features that something like info provides (e.g. there are no browsing links - there used to be a pseudostandard with special <link> tags, but it was only ever supported by classic Mozilla/SeaMonkey and it never caught on). EDIT: i see some of those are authored in DocBook but still info files can in theory be written in DocBook too. The main focus of my comments here is the end user format and viewer capabilities, not the authoring format (and honestly i'm not a big fan of info format with its hardcoded text formatting).

by anjbe 7y ago

Crinus 7y ago

I know, but writing a coherent manual is a different task than writing a short reference page, especially if you want to include more content than just a reference (e.g. user guides or tutorial sections) and writing text that assumes inline hyperlinking is always available. Note that this isn't about it being technically impossible, you can certainly do it, but it isn't the right tool for the job - a dedicated manual reader provides a better UX here (and the failure of GNU info to provide a user friendly experience is, IMO, the reason manpages are abused so much in Linux).

JdeBP 7y ago
You're talking about the grossly-misnamed (since large portions of it do not contain any questions) OpenBSD FAQ, which is where guide and tutorial stuff is to be found. BSDs (and some others) come with variously-named Handbooks. OpenBSD has the aforementioned. FreeBSD has a Handbook. So do DragonFly BSD, NetBSD, and others. They are distinct from the user manuals, which are the reference doco. They are, indeed, hyperlinked. Already. * OpenBSD FAQ: http://openbsd.org/faq/index.html http://openbsd.org/faq/index.html * NetBSD Guide: https://netbsd.org/docs/guide/en/ https://netbsd.org/docs/guide/en/ * FreeBSD Handbook: https://freebsd.org/doc/handbook/book.html https://freebsd.org/doc/handbook/book.html * DragonFly BSD Handbook: https://www.dragonflybsd.org/docs/handbook/ https://www.dragonflybsd.org/docs/handbook/ * GhostBSD Handbook: https://wiki.ghostbsd.org/index.php/GhostBSD_User_Handbook https://wiki.ghostbsd.org/index.php/GhostBSD_User_Handbook * MicroBSD Handbook: http://damnsmallbsd.org/MicroBSD/handbook/ http://damnsmallbsd.org/MicroBSD/handbook/ * OpenIndiana Hipster Handbook: http://docs.openindiana.org/handbook/getting-started/ http://docs.openindiana.org/handbook/getting-started/ * old TrueOS User Guide: https://trueos.org/handbook/trueos.html https://trueos.org/handbook/trueos.html
- Crinus 7y ago
  I'm not talking about any specific guides or manuals, but yes the OpenBSD FAQ, FreeBSD Handbook, etc are the sort of manuals i am talking about. But those are not made in manpage format and at least the OpenBSD FAQ HTML pages seem to be edited by hand. And since those are in HTML (at least the OpenBSD one, i didn't look into the others) they lack the indexing and ebook-like reading features that something like info provides (e.g. there are no browsing links - there used to be a pseudostandard with special <link> tags, but it was only ever supported by classic Mozilla/SeaMonkey and it never caught on). EDIT: i see some of those are authored in DocBook but still info files can in theory be written in DocBook too. The main focus of my comments here is the end user format and viewer capabilities, not the authoring format (and honestly i'm not a big fan of info format with its hardcoded text formatting).