Currently, Anki’s man page is close to useless, not very consistent (one option is shown as -b ./.anki, where ./.anki can be replaced with the wanted path — that is, the option is shown with an example; an other option is shown as -l <lang>, where <lang> should be replaced with the wanted language — that is, the option is shown with a variable-like syntax) and outdated (it’s from 2007…). Contrast this with the very high-quality manual that we have at docs.ankiweb.net, which is very consistent, clear, exhaustive and to the point. It’s a bit of a shame…
Which is why I would suggest using a tool like mdbook-man to be able to generate a very good man page out of the current documentation with almost no efforts: it’s just adding an output in the book.toml.
Otherwise, I might also start maintaining it “by hand”. Since I’m currently not acquainted with Anki’s code, I’ll have to start with a conversion from the manual, but I plan to start packaging properly Anki for my Linux distribution in September, which means I’ll finally be able to contribute to it (and thus be able to write proper documentation on my own, rather than just translating already existing documentation).
The existing man page was contributed by a distro packager, presumably because a man page was required by their packaging policies. I don’t really see the value in it - there aren’t many command-line options, and they are more exhaustively listed with --help.
I’m not sure about trying to convert the manual to a man page. In my experience, man pages tend to be short and focused on documenting command line usage, and without a way to navigation to various sections quickly, the user would need to rely on searching. It’s also often the case that improvements to the manual are made after a release, so the generated man page could potentially be stale.
A man page is absolutely not only for documenting command line options. Just look at the man page for bash (and the manual pages I consult the most are tens of thousands of line long, where the Bash one is only about 3.5k lines). The man pages are meant to document any feature a program might have. In my machine, there is a man page for every CL function and macro and for every configuration file, besides man pages for commands (and actually many more!). Basically, it’s a standard way to have offline documentation.
Besides the fact that it’s already how I navigate in the current manual, I think most people who use man pages are used to navigating like that.
In fact, for very complex pages like that, there is an other standard documentation tool, which is GNU Info. An Info page is closer to a web page than a man page, because there is more formatting, and there are links between different pages or sections in a single page. It has some more features (for instance, the official Emacs tutorial is an info page), and different info readers provide different level of features themselves (for instance, there is the info utility itself, but Emacs is also an info reader).
It’s not really an issue for the manual, so I don’t think it would be an issue for a man page. A man page can also specify the version of the program it is meant for.
As counterexamples, look at the man pages of GUI apps like libreoffice, google-chrome, firefox, and the gimp. They are short, and some of them specifically redirect the user to the web for more info, such as
OTHER INFO
The canonical place to find GIMP info is at https://www.gimp.org/. Here you can find links to just about many other GIMP sites, tutorials, data sets, mailing list archives, and more.
There is also a GIMP User Manual available at https://docs.gimp.org/ that goes into much more detail about the interactive use of GIMP.
and
DESCRIPTION
See the Google Chrome help center for help on using the browser.
<https://support.google.com/chrome/>
This manpage only describes invocation, environment, and arguments.
Given that, and the fact that I don’t really want to add extra steps to the release pipeline, I’m afraid I’m not really keen on such a change at the moment.
And it’s why they are arguably bad man pages (in the sense that they don’t fulfill they man page role). Except for Gimp, since its documentation requires a lot of images, and is thus inherently incompatible with the man format.
Short and to the point offline documentation that mainly explains command line arguments is the role of tldr.
I understand that, and since you have the final word on the decision anyways so there is no arguing further in this direction.
I too see no point generating a man page. We already have the manual in a useful, navigable, thorough, and easy-to-use format. Why confound users of Anki by producing yet-another in some other rarely used form.
By far the greater majority of Anki users will be using it on a mobile device or on a Windows computer — neither of which would benefit much from a man page.
I honestly think no one would ever be confused by the existing of a man page. Think of it the other way: if you are an experienced user on a system which uses man pages (that is, all Linux distributions, probably BSD and maybe some other Unix-like?), you expect the documentation to be available in the form of the manual format, because that is a useful, navigable and easy-to-use format because it is standardized. This means that a lot of other components work well with manual pages, ranging from a variety of man pages readers (that the user can choose from, which can provided any form of formatting, which is then consistent for all the documentation — as opposed to having online documentation, where each site usually provides a single performatted manual, and which is not consistent across different software), to extensive utilities to search and classify these man pages (since their format it standard, it’s easy to do this kind of things). This is why man pages are very practical even though they do not contain links. Usually, the alternative are Info pages, which are basically man pages with links (and a few other features).
Note also that, usually, man pages are very reliable, because most Linux distributions have a policy which strongly recommends (or even forces) the packager to also provide a man page.
If, on the other hand, you’re not used to man pages, you would probably never even notice Anki had a man page (actually, Anki already has a man page; I don’t think you’re confused about that…).
First of all, I have access to man on my mobile device (and it’s a regular Android phone), and Windows users can also read man pages (see groff) — provided they want to, which is usually not the case.
But that’s not really the point. I agree that it wouldn’t be a big change overall, but it’s also extremely easy to make it happen (it’s about adding a line to a file), so it would be a very cost effective thing to do. Having a great impact and being worth doing are not the same thing.
I use man pages regularly: for information about C functions or constructs, or other UNIX-specific or LINUX-specific CLI shells or programs.
I doubt many would look for a man page about an application with a GUI. We’ve be trained since Windows 2 to seek a Help button, or later in the 1990s to look for a web page.
I am not trying to say that there is anything wrong with man pages, or an Anki man page, if you wished to create one. I just think that you could count the users, who might benefit from such a man page, on the fingers of one hypoplastic hand.
I think you are somewhat underestimating the work required to add it to the build steps on all three platforms and test it works, and not considering the impact it may have on build times or future maintenance.
Linux users comprise a small percentage of the total desktop userbase (something like 3%), and those who would make use of a large man page are probably a small portion of those users. I’m afraid I can’t justify it at this time.
I understand. Then, it wouldn’t hinder you if I were to update the man page? Not adding it to the build process, but simply making a one time update (just because it’s currently very lacking).
Yes, that figures. However, I’m just curious about how do you get that 3% number? Do you collect statistics on running instances or Anki, or is it based on the downloads? Because, even though it’s not officially supported, some users still install Anki through their package manager, which is hard to count, or some distributions might even mirror Anki’s sources or binaries (the distribution I use for instance does something similar).
