Joplin man page

[Daeraxa]

So the latest thing in my quest to provide solutions to problems that nobody has is to see what a proper man page for Joplin (the CLI app) could look like.

I've been using the terminal app a lot recently (and yes, as ever I have some thoughts on it) and this was just something that stuck out to me as a little bit of an absence.

Unfortunately due to some of the formatting changes it won't be easy to simply automatically update it from the real help command or documentation (some of it was automated but much was still handcrafted).

If I was to do this "properly" I think the entire config section could be split out to its own (7) page as well as cleaning up some of the terminology/syntax like option, command, subcommand etc. but this is really just a proof of concept and for my own satisfaction.

To copy the readme from my repo of other such random things:

JoplinMan

No not a note taking superhero, just an attempt to see what a Joplin (CLI) manpage would look like.

Created in Markdown (with some odd formatting choices because of 1) the conversion process and 2) some potentially reserved names (like name which refused to have proper formatting when converted)).

The .md is then converted with pandoc, compressed, placed in the local man dir and the man db updated.

If you want you don't have to use the .md file and pandoc at all, the groff (.1) file can be edited directly but isn't the friendliest thing to read or edit, hence doing it in markdown and converting.

If you want the files to install it yourself then they are on my GitHub along with the instructions to build/install it on your own system.

Below is an image of what it looks like in a terminal window:

[ernstki]

@Daeraxa

So the latest thing in my quest to provide solutions to problems that nobody has is to see what a proper man page for Joplin (the CLI app) could look like.

Command-line utilities and well-written man pages are like peanut butter and chocolate: two great tastes that taste great together.

I applaud your efforts, and will gladly donate a hand-crafted, artisanal Makefile to the cause, if you feel that would enhance the project.

I have not looked at Joplin's own build system (yet), so I can't say for sure if that would jibe with whatever npm-based thing might already be in place, but there's much to be said for the rustic charm and versatility of Makefiles, even in that context.

[laurent]

By the way, is this man file something we can add as part of the build system, or is it something to be installed separately?

[Daeraxa]

So to do it manually you just need to get the x.1.gz file (which is what man actually uses), place it in the man directories (in my case /usr/local/man/man1) then run mandb.

However the npm docs do specify how to include a man page as part of the package.json:

package.json | npm Docs

Which, I think, doesn't install it to root like my example but creates a link to it so that when man is called it will look in the installed bin dir.

{
  "name": "foo",
  "version": "1.2.3",
  "description": "A packaged foo fooer for fooing foos",
  "main": "foo.js",
  "man": "./man/doc.1"
}

The main challenge really would be to have an automated way of creating the man page unless we want to add another documentation area to remember to update.

[laurent]

The output of joplin help is already relatively structured and dynamically generated. Maybe it's possible to use that, or we could even tweak the help command to output it in a different format in this case, using something like joplin help --format=man.

[Daeraxa]

I would need to look into what is easily automated (or to be honest how the existing one is automated) as I ran into a few issues with adapting the existing help structure.

1. A man page should have/needs additional elements beyond what is provided in help, my one featured Name, Synopsis, Commands, Examples, Files, Issues and Copyright sections - only the Commands section was taken verbatim from help all, the rest was created from scratch or from the website.
2. Some kind of conversion into the (g?)(t?)roff format, I did this via pandoc so I'm not sure where this step would need to take place when considering some kind of automated approach.
3. Some formatting has to change in order to make it "look right"
   • Removal of newlines in the command explanation
   • Pandoc .md -> man really didn't like <name> and just blanked it - didn't look further into it, just changed the bracket styles in a few places
   • Additional bolding of commands etc.

The config section was quite difficult to work with and makes the page a little unwieldy as really I think it should have its own man(7) page but that isn't something I implemented and would also need a bit of work.

@ernstki mentions using makefiles to generate this instead? Not sure if you would want an additional build process in place or not though and (from lack of knowledge) I don't know if this makes life easier or not - maybe you could elaborate on how it might be beneficial here ernstki?

There might also be a bunch of general manpage conventions that I have violated so happy to be corrected on what the correct usage is (for example naming scheme/bracket style of things like "command" or "option" etc.)

I'll have a bit more of a tinker around with this when I can, see what other projects do (especially node projects) and see if I can come up with some kind of proof of concept.

[laurent]

The function to generate the output of joplin help is this one: joplin/help-utils.js at 80b16dd17e227e3f538aa221d7b6cc2d81688e72 · laurent22/joplin · GitHub

So there's direct access to the various elements, such as the command name, arguments, etc. which should make it possible to create a custom rendering.

I guess the workflow on CI could be to call joplin help --format=man > /path/to/joplin.md to generate that man page, or could even be done manually from time to time since the help file doesn't change very often.

[ernstki]

@Daeraxa

@ernstki mentions using makefiles to generate this instead? Not sure if you would want an additional build process in place or not though and (from lack of knowledge) I don't know if this makes life easier or not - maybe you could elaborate on how it might be beneficial here ernstki?

Just that the steps in your README seemed well-suited for a Makefile, that's all. A Makefile is basically shell script with some extra syntax (significant whitespace, mostly) for expressing task dependencies, with no extra layers of quoting.

But if npm is already in use for the rest of the project—which I imagine it is—then perhaps it's best to stick with that system instead. Not every Windows system is going to have a make command anyway.

The docopt guy claims there's a POSIX standard for man pages, but I have not chanced upon it yet. For the basic structure of a man page, I often refer to perlpodstyle. It also looks as if some (Linux?) systems have man-pages(7) which is basically a style guide.

[ernstki]

@Daeraxa

There might also be a bunch of general manpage conventions that I have violated so happy to be corrected on what the correct usage is (for example naming scheme/bracket style of things like "command" or "option" etc.)

C.1.5 Utility Description Defaults from the "Rationale for Shell and Utilities" chapter of IEEE Std 1003.1 looks like the go-to for what sections are included in a "standard" man page. Or one possible authoritative source, anyway.

[Daeraxa]

That's a nice source, thanks. I've only just got access back to a proper PC so I'm catching up on a million and one things but I do intend to have another stab at this when I can.

[tpiekarski]

Excellent, Daeraxa thanks for the manual page.

@Daeraxa

So to do it manually you just need to get the x.1.gz file (which is what man actually uses), place it in the man directories (in my case /usr/local/man/man1) then run mandb.

Create rather symbolic links to keep that file in its repository and have the convenience to update it with a git pull