Template talk:Man

From ArchWiki
Jump to: navigation, search

Upstream contributions

I'm wondering if we could collaborate with the maintainer of man7.org on adding some common missing manuals and fixing things like broken links to multiword sections at the top of each manual and inconsistent anchors (e.g. mount(8)), which are most likely problems of the HTML generation tool. -- Lahwaacz (talk) 19:12, 26 August 2016 (UTC)

I wrote a mail to man-pages@man7.org regarding the inclusion of pages for pacman, mkinitcpio and netctl in July (following [1]), and haven't had a response yet. That said, in the mean time there's been no new release of man-pages either, so they might as well be included later.
For bug reports, see [2] -- Alad (talk) 05:03, 27 August 2016 (UTC)

Section 1p

locale(1p) is broken. It produces link to http://man7.org/linux/man-pages/man1p/locale.1p.html, but man7.org has that man page in http://man7.org/linux/man-pages/man1/locale.1p.html. Looks like letters need to be stripped from man{{{1}}}. -- nl6720talk 12:34, 6 October 2016 (UTC)

Without enabling other extensions, I think it can only be done with #switch. Otherwise there's #sub (StringFunctions is installed but not enabled) or even mw:Extension:RegexParserFunctions, but I'd say that would be overkill... — Kynikos (talk) 12:07, 7 October 2016 (UTC)
Or we could simply make the template composing instead of splitting, so the above would be written as {{man|1|subsection=p|locale}}. -- Lahwaacz (talk) 12:29, 7 October 2016 (UTC)
These should work: {{#switch: {{1}} | 0p = 0 | 1p = 1 | 3p = 3 | {{1}} }}, {{#sub:{{{1}}}|0|1}}. Is there any chance of getting #sub enabled? -- nl6720talk 14:39, 13 October 2016 (UTC)

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 [3] and [4]). 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 mandocAUR 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)