More visibility for man pages from haikuports

With spropos (the man page topics presenter tool) now working, I am impressed with the amount of information and knowledge that is contained in the man pages now on Haiku.

I have learned that the main Haiku development does not use man pages, preferring to document things with HTML pages. Fine. But the majority of things in haikuports though are from environments that rely on and provide man pages.

Recently I saw conversations go by that discussed whether recipes in haikuports with man pages should run a post-install run of ‘makewhatis’ (the man page indexer). Running ‘makewhatis’ does not take a lot of time so I would vote for that. I haven’t looked through haikuporter enough to know if there is support for s ‘post-install’ step, or triggers for running such a step exist, but they sound like a good idea. Having a post-install step and a trigger, for example, on providing an install of a man page would have this indexing just happen without needing to modify recipes. And it would continue to work for new items in the future.

Regardless of the above, with the man page environment now working, I have been musing about writing a ‘Manpager’ application that would provide searching and presenting man page content. Still haven’t decided on it.

Thoughts?

I vote against adding a post-install script for that as it would make package installs slower.
Having nearly-instant package installs and uninstalls is one of the major features that no other operating system has,but Haiku does.
I agree with the idea in the other topic that man/apropos should ideally detect an outdated database automatically and update it when the tool is used.
That would reduce the waiting time to the people who actually use it.
Since that’s likely not possible without making major changes,my opinion is that having to manually run the makewhatis command in case you actually need it (most people likely don’t) is more acceptable than delaying package installs for everyone.

The first PR for that was accepted yesterday; the Scribus port now runs makewhatis post-install if the mandoc package is installed.

I submitted the PR for the mandoc port this morning to have it run makewhatis in its post-install.

I understand the objection; if you don’t have the mandoc package installed, though, the script exits immediately so there’s negligible slowdown for folks who don’t want apropos.

You can’t uninstall mandoc without also uninstalling git,just tried.
Is mandoc really a hard requirement for git?
The Arch Linux page doesn’t list mandoc as dependency for anything (only optional or as build dependency):

Well. I didn’t anticipate that problem.

I’m no git expert, but I can’t see how apropos of all things could be a real dependency there.

Just did a build for latest git version 2.56.0, no issues dropping cmd:man or cmd:nano (look weird to me also), I’ll run some tests before pushing the update to make sure all is still working as expected (current status).

Another build option there was to disable rust, don’t want to pull that in if we can miss it for now. :slight_smile:

1 Like

I just searched the $PATH for ‘man’ and the one from mandoc seems to be the only ‘man’ command; so if man is a POSIX requirement presumably this means the mandoc package is installed with the base system?

Not that I have any problem with letting folks uninstall packages that come with the base system, of course. If you’re not gonna use it, there’s no reason you should have to keep it around.

Please don’t do this, mandoc is part of the base install because of posix compliance (since it suplies cmd:man) (or actually, I’ve not checked this, it could be because of git. But if it is not it should be)

Can we please not have package installs slow down just because of this?

Git supplies it’s doc in html and man, if the result of man is having each package now running a post-install script it would be better to remove the manpages entirely and move them to some _man subpackage instead…

Or someone could fix man to not need such archaiv mechanisms and just update it’s cache on demand as other modern tools do

Not that I have any problem with letting folks uninstall packages that come with the base system, of course. If you’re not gonna use it, there’s no reason you should have to keep it around.

We don’t currently have some kind of “meta” package for posix compliance, but I would very much assume that if some app sais “it needs posix” you would not expect the user to deinstall random packages because they don’t seem usefull at the time. It’s perfectly possible that some app for example would invoke man on it’s own to show documentation, that it itself ships, because it expects this to be the proper (or atleast a possible) way to do it

2 Likes

For Haiku you might consider a translator, a translator transforms from one format to the other. In this case the input format would be the man-compatible markup language, and the output format could be html. With this setup you could then view all documentation in a single application, and can have niceties like a chapter index, and clickable hyperlinks to other content (i.e other manpages)

It’s not man; it’s whatis/apropos, which is in the mandoc package along with man.

All this furor about slowing installs down made me wonder just how big an effect we’re talking about here, so I made packages both with and without the post-install script and timed them.

It’s a tiny effect; far smaller than the variance in install times is. I got install times between 5 and 9 seconds on both packages; after several runs, the fastest time for each was:

pkgman install scribus_without_makewhatis-1.6.6-5-x86_64.hpkg

0.62s user 0.11s system 13% cpu 5.563 total

pkgman install scribus_with_makewhatis-1.6.6-5-x86_64.hpkg

0.61s user 0.10s system 13% cpu 5.108 total

In fact, as you can see, it’s such a small effect that the other steps completely drown it out and in the tests above the one with the post-install actually ran faster than the one without.

So, honestly, we absolutely do not need to concern ourselves with adding this step to packages that carry man pages.

We absolutely need to, if it is not, at the very least, centralized as only one script to run. Otherwise it is just more lines of code for reviewer to possibly miss, on every single recipe.

3 Likes

Hah; ok. :slight_smile:

I was only referring to whether the increase in install time is worth worrying about; I realise that I wasn’t clear.

I couldn’t figure out a better way that I could do in the time I can put in, though; as I said on github though I’m totally open to better suggestions.

Why do you think this? You performed this test once with one package, but you are asking for pretty much every package to get a post-install step… having a step vs not having a step is certainly slower. Not having a post-install step is atomic, but adding one removes the atomicitiy.

You can now no longer install packages irrespective of their ordering

For example if you first install git and then mandoc you now again have a state you do not want the system to be in; the timing is not the main issue here. the solution is simly the wrong one; the nice part about Haiku is that we can make the right solutions if needed… and this is here fixing the mandoc package, not modifying litereally every recipe that ships man files

2 Likes

Honestly I wouldn’t care much about the search feature. Man pages work without the DB. People using man pages should know a bit how it works, and they may have to run makewhatis.

Arch Linux runs indexation once a day, so it must not be so important IMO.

1 Like

Actually that is kind of what I have done with an Apache cgi-bin python package that takes the output of man, parses it, pretties it up, turns manref(section) occurrences in text into links to the other pages, turns http[s]: references into links to those pages, and as an extra bonus takes the output of apropos into a searchable set of links too the man pages, And a pre-cull selection of what section is of interest. And it works across my collection of VM systems. Which is what I’m adding Haiku to.

So the browser is the UI environment where I leverage it’s formatting and controls. Which makes me wonder, is there an Apache (or similar) web server now on Haiku?

Apache web server is available in the HaikuPorts repository.
Nginx and lighttpd,two other popular webservers,are there too.
And there’s also PoorMan,a tiny web server that comes preinstalled with Haiku,but I’m not sure if that’s suitable for your needs.

And when PoorMan feels like too little, there’s RobinHood to the rescue!

Poorman is in the base system, but depending on what you actually want to acomplish there is no need for a http server at all. Webbrowsers can work with the “file:” protocol just aswell,

for example the default welcome pages and such are loaded like this “file:///boot/home/config/settings/WebPositive/LoaderPages/QuickTour”
(this should be file:/boot but webkit does something stupid here… for a later time to fix)

If you use proper relative links in your <a>elements you can construct your entire documentation like this, without the use of any webserver for local consumption by the user.

Note also that ideally we would use a documentation viewer app that presents html, and not the webrowser itself… but there is no such app yet. there probably will be when webkit2 is ready, it will be much easier to write an app using webkit componenets then.

EDIT: super creepy that typing a “a” tag instantly makes discourse render the rest of the message as a uri… but it vanishes from the source message, wtf

OK. I have Haiku integrated into my fetchman suite, The big issue was that the Haiku apropos output has multiple entries per line whereas other systems (Solaris, MacOS, Linux, FreeBSD, Windows w./CYGWIN) present things one actual man page per line.

That is all great and good, and I initially took all the entries on the lines to reference man pages. And many of them do. But a few dozen of them don’t, which leaves me wondering just how the ‘man page-less’ entries got onto the lines. I have opened ticket #14925 at the haikuports wiki about this.

The HTML formatting works with the Haiku pages, so things are pleasantly presented. Cross man page linked references for the SEE ALSO sections and other references work.

As to getting this running on Haiku, well there is a bit of an issue. My CGI scripts are built to operate at launch using a set of bash functions that operate with a configuration file that describes multiple virtual machines to communicate with. The bash functions do things like support the VM at startup to deposit it’s DHCP assigned address into a shared location, check if he VM is running, get the VM’s hostname, and add entries into the hosts file as appropriate. And some other tasks. These VMs are how I host these systems. The scripts use ssh (with GNU sshpass) to interact with the VMs. I have multiple desktop launchers for each one, so they are easy to start.

So things are built to operate in my environment. Which is nice for me, but doesn’t carry over to running in the Haiku environment. So to get things to operate running on Haiku will need me to re-write/re-package things. No promises as to when I will get around to this.

And I have very purposely written things in a CGI fetch, transform, and present model as 1) I don’t like the use of storage space for copies and 2) I want to adapt is new pages are added.

So, any Haiku port will be on a web server with CGI model. Probably Apache.

Thought I’d share.

If anyone would like copies of what I’ve written, let me know.

Thinking about things.

Should I use haikuports for my new Manpager application even if it isn’t a true ‘port’ of an application? It seems to me to be the way to go. I can create a git repo at github. I can also read/learn all the options from other recipes and the various web pages about haikuports.

What I am envisioning is something that requires both Apache and Python to be installed. The main application would be a bash script that would allow the user to choose the browser with an environment variable BROWSER to chose WebPositive (default) or Firefox with an argument of http://localhost/cgi-bin/Manpager.py to kick things off. Also support a -help argument to explain things.

The .hpkg generated would place the starting bash script in /boot/system/packaged/bin, the CGI script in wherever Apache needs it. Pretty bare bones.

Does this make sense using haikuports to add a new (not ported) application?