Template talk:Man

Sources

manned.org has an index of man pages from Arch's repos, so I think that should be the preferred source for the url= parameter. And although I have no problem with man7.org, maybe manned.org could even become the new default to keep things 100% consistent. Then the url= parameter might be even unnecessary. -- Lahwaacz (talk) 07:58, 15 March 2017 (UTC)

The reason I went with man7 in the original template is that it doesn't require Javascript and has clear subsections (compare [1] and [2]). That said, contributing to man7 has proved fruitless so we might as well take a new route. -- Alad (talk) 14:08, 15 March 2017 (UTC)

manned.org can be viewed without javascript, so I wouldn't say it's required. But the subsections would be a problem, as well as the fact that the origin of the man page is not shown by default, which might bring even more confusion. So there goes the idea of making it default... -- Lahwaacz (talk) 14:57, 15 March 2017 (UTC)

We should definitely switch to manned.org. man7 disqualifies solely because it lacks many pages eg. autoconf(1), tcpslice(1), pcap-filter(7), tracker-sparql(1), named(8) ... etc. While manned.org has 275,478 man pages man7 only has 9,864. A template is supposed to prevent duplication, not to create it. With man7 nearly every software article needs to use url=http://sitethathasmanpage.org/foo. Isn't Arch's philosophy to keep it simple? man7 is also technically inferior to manned.org since it doesn't link page mentions and doesn't provide a built-in search and just redirects to Google. I agree that the subsections on manned.org are too subtle but manned.org is open source and I am sure the creator will accept pull requests. -- Larivact (talk) 07:40, 17 April 2017 (UTC)

+1 to change. Of course being able to link to subsections/page chapters is neat, but I have not seen it being used often (ideally needs cross-checking before). So, I think too it is clearly outweighed by being able to link to the current version and that for all official repo packages.

In fact, as I understand it's about, it will prefer latest upstream stable as default. I think it may be even useful to consider to the project's generic link (e.g. pacman.8). The benefit here is that it will even cover AUR packages (assuming AUR is up-to-date maintained:) and we won't have to track when a package moves from/to AUR/repo or vice versa. --Indigo (talk) 16:53, 17 April 2017 (UTC)

So our requirements are:

• All man pages from official Arch packages are available. Old versions and permalinks are not necessary.
• Functionality does not require Javascript.
• Pages are addressable by their name and section, both occurring exactly once in the URL. Note that there are pages like ar(1) and ar(1p) and the latter link is currently broken.
• Human-readable subsection anchors. Note that man7.org is not ideal, sometimes it confuses with a _.
• The URLs used by the template should not redirect to permalinks (or anywhere else), otherwise bots will be unable to check that manually inserted (and possibly outdated) URLs lead to the same page as the template.
• The page should clearly indicate the Arch package version containing the page. manned.org needs Javascript to show this info when the user clicks something.

(If I forgot something, feel free to add it to the list.)

At this point we might as well start building our own service. Hosting is probably not a problem, I might abuse my workstation at school (which should get a DNS record soon). When we're done developing and testing, we could try to convince the Arch developers to host it on archlinux.org.

-- Lahwaacz (talk) 16:26, 23 August 2017 (UTC)

It would be a super super service to the community at large (incl downstream distros, smaller linux projects, etc.) to provide such. Though, I'd be warry to secure project support for it first, once a rough plan how to implement it is worked out. Any such development must fit existing infrastructure, to be easily long-term maintanable etc. It sure would take time, so better know before there are good dice for it moving to man.archlinux.org.

I think we could benefit from switching to manned.org in any case, even if it's for a medium term - templates are flexible. Btw: If we use the generic link (e.g. pacman.8#head18), version info is displayed even without javascript just like with man, at the bottom of the page. So the only missing feature are subsection anchors, that's minor to me as I wrote above. --Indigo (talk) 20:04, 23 August 2017 (UTC)

That version info at the bottom is only a courtesy of some packages, it's not everywhere: see e.g. ssh.1. Also, if we use these generic links without specifying the system, we have no guarantee that we get the same manual as Arch ships. Although it seems to be the same for all pages I've checked so far, it's still a concern. -- Lahwaacz (talk) 20:20, 23 August 2017 (UTC)

As for the technologies, the choices are pretty obvious for me: Python as the scripting language, couple of packages as necessary dependencies, Django as the web framework (also used for the main archlinux.org website), some SQL database... I don't think that the devs will have any problem with that - the storage requirements and workload due to updates might be problematic, but there is nothing we could do about that.

I've already started working on it and have an almost working proof of concept, so stay tuned!

-- Lahwaacz (talk) 13:44, 25 August 2017 (UTC)

So you can finally try this demo :-) I'm going to leave improving page layout and CSS stylesheets up to you guys, but let me know if something else does not work as expected... -- Lahwaacz (talk) 08:14, 26 August 2017 (UTC)

Wow, terrific (adorable fast uplink btw). I'll take a while but certainly will go bug scouting :) --Indigo (talk) 20:25, 26 August 2017 (UTC)

Thank you Lahwaacz, it's an amazing job! I'll certainly help with the styling when I'll find some time if nobody beats me to it. -- Kynikos (talk) 05:10, 27 August 2017 (UTC)

Great, looking forward! Styling is about the only big thing missing, since I've found that a newer version of mandoc^AUR creates links to sections/chapters. I've also improved the URL scheme (described on the demo page), but linking to man pages whose name contains a dot is broken. Assuming that I can easily fix that, all the requirements should be already met ;-) -- Lahwaacz (talk) 13:14, 28 August 2017 (UTC)

Update: the URL scheme should be fully functional now and I've written a quick-start guide for anybody who would like to start working on the design. -- Lahwaacz (talk) 13:06, 29 August 2017 (UTC)

I just couldn't wait so I started with the styling, have a look! In the end styling the content of the man pages isn't so hard, because the OpenBSD site has great copy-pastable stylesheets, but a downside of this approach is that both sites look almost the same, so I'll still need to hire the professional designers (i.e. you) to make the difference ;-) Lahwaacz (talk) 21:46, 1 September 2017 (UTC)

I've also made a simple searchbox field and fixed an important usability issue regarding the .so macros. So I think it is time to switch the template to point to the new site, we can always finish it later. -- Lahwaacz (talk) 17:33, 4 September 2017 (UTC)

Sorry for the quick reply, but +1 from me to update the template! Perhaps this could even be proposed to become an official Arch project... -- Kynikos (talk) 15:56, 5 September 2017 (UTC)

Alright, I've updated the template! Let's see what happens next... -- Lahwaacz (talk) 19:15, 6 September 2017 (UTC)

Thanks Lahwaacz, the pages are great. I also support it as an official Arch project. An archlinux.org subdomain is also needed.--Fengchao (talk) 09:49, 16 October 2017 (UTC)

I think the style can be further improved. For example, on rsync(1) some commands are not monospaced, and some indentations don’t look right in OPTIONS section. --Franklin Yu (talk) 03:16, 4 April 2018 (UTC)

The website just renders what the man->HTML converter (mandoc^AUR) produces. And the converter can't magically format all badly written man pages nicely. In particular, pages written in the mdoc(7) format look much better than those written in the old man(7) format, which is not so rich.

That being said, if you have some improvements for the CSS stylesheet, feel free to submit a pull request!

-- Lahwaacz (talk) 14:39, 16 August 2018 (UTC)

Showing anchor links

I think Template:Man should show anchor links like this: intro(1)#NOTES to make them obvious. –Larivact (talk) 14:24, 23 December 2017 (UTC)

That might be confusing for the reader. -- nl6720 (talk) 14:27, 23 December 2017 (UTC)

We already show anchor links for references to article sections, if SSH keys#SSH agents isn't confusing I don't see why intro(1)#NOTES should be. --Larivact (talk) 14:38, 23 December 2017 (UTC)

On second thought, I have no objections to this proposal. -- nl6720 (talk) 06:37, 22 April 2018 (UTC)

There will be a problem with the way the links look since currently spaces in chapter titles need to be manually changed to underscores. E.g. the mount(8) § FILESYSTEM-INDEPENDENT_MOUNT_OPTIONS used in the Template:man#Example, its chapter title is "FILESYSTEM-INDEPENDENT MOUNT OPTIONS", but the template needs "FILESYSTEM-INDEPENDENT_MOUNT_OPTIONS". -- nl6720 (talk) 06:35, 22 April 2018 (UTC)

We can use {{anchorencode:FILESYSTEM-INDEPENDENT MOUNT OPTIONS}}. I just hope that the underscores are consistent... -- Lahwaacz (talk) 07:28, 22 April 2018 (UTC)

I don't get your last sentence.--Larivact (talk) 11:42, 22 April 2018 (UTC)

Are we sure that underscores are used instead of spaces everywhere? -- Lahwaacz (talk) 12:21, 22 April 2018 (UTC)

Man pages do not define ids for headings, mandoc automatically derives them from the heading. See the html_make_id function in html.c. --Larivact (talk) 14:27, 22 April 2018 (UTC)

Even without showing anchor links, the anchorencode would be useful by allowing to specify proper section names. Could it be added? -- nl6720 (talk) 11:22, 5 June 2018 (UTC)

Sure. I don't mind showing the anchors either - are there more opinions? -- Lahwaacz (talk) 17:28, 8 June 2018 (UTC)

I found a problem with anchorencode. I wanted use {{man|1|resolvectl|COMPATIBILITY WITH RESOLVCONF(8)}} which should link to https://jlk.fjfi.cvut.cz/arch/manpages/man/resolvectl.1#COMPATIBILITY_WITH_RESOLVCONF(8), but anchorencode encoded the brackets: COMPATIBILITY_WITH_RESOLVCONF(8). Also https://jlk.fjfi.cvut.cz/arch/manpages/man/resolvectl.1 doesn't even list the section in the table of contents. -- nl6720 (talk) 09:38, 16 July 2018 (UTC)

Wow, that's funny: if you try {{anchorencode:x y z á é ( ) * & : / {{!}}}} on the ArchWiki, it produces x_y_z_á_é_(_)_*_&_:_/_|, but on mediawiki.org it gives x_y_z_á_é_(_)_*_&_:_/_...

Anyway, I fixed the section not showing in the table of contents: [3]

-- Lahwaacz (talk) 08:49, 14 August 2018 (UTC)

Apparently it is affected by the mw:Manual:$wgFragmentMode setting. -- Lahwaacz (talk) 09:04, 14 August 2018 (UTC)

I created a pull request to start the migration to the new HTML5-style fragments, which should also solve this problem. -- Lahwaacz (talk) 11:28, 14 August 2018 (UTC)

Yay, it works now! Special:Diff/554670. -- nl6720 (talk) 12:32, 11 November 2018 (UTC)

Bumping this again, revisions like [4] look awkward because unless you hover over the links, it looks like the manual page link is simply repeated 20 times. -- Alad (talk) 09:34, 1 August 2019 (UTC)

So the fragment should be always visible if the third parameter is provided? I think that would be fine, but just changing the template might lead to unintended formatting if the surrounding text assumes that the fragment is hidden. E.g. the section name might be repeated after the link itself. -- Lahwaacz (talk) 19:12, 1 August 2019 (UTC)

Well, I guess it will be faster if we just show the fragment and let people update the surrounding text if needed... We'll also need to add another parameter to override the default anchor-url-encoded fragment - there are many sections like e.g. [5], [6], [7] which can't be linked to using just MediaWiki's encoding functions. -- Lahwaacz (talk) 21:23, 6 August 2020 (UTC)

Template updated, let the bikeshedding begin! -- Lahwaacz (talk) 22:12, 6 August 2020 (UTC)

Show external link icon when url parameter is given

Should be possible by replacing plainlinks with {{#if:{{{url|}}}||plainlinks}}.

--Larivact (talk) 19:06, 16 January 2019 (UTC)

Enable Language selection

It would be nice to have a field for language selection as some man pages have translations. Alternatively, implement content negotiation in the upstream website to have user's language automatically selected.

Example:
default: https://man.archlinux.org/man/bash.1
French: https://man.archlinux.org/man/bash.1.fr

-- Josephgbr (talk) 11:32, 6 January 2021 (UTC)

I would prefer an automatic selection, if it can even work. See also [8]. -- Lahwaacz (talk) 12:32, 7 January 2021 (UTC)