On Thu, Jan 19, 2017 at 4:41 AM, Paul Wise <p...@debian.org> wrote: > On Thu, Jan 19, 2017 at 1:23 AM, Michael Stapelberg wrote: > >> https://manpages.debian.org has been modernized! We have just launched >> a major update to our manpage repository. What used to be served via a >> CGI script is now a statically generated website, and therefore >> blazingly fast. > > My dman shell function is now broken: > > dman () { > w3m "https://manpages.debian.org/man0/$1" > } > > The manpages.d.o URLs on these pages are broken: > > https://wiki.debian.org/AppArmor/Debug > https://manpages.debian.org/man/0/aa-notify > > https://wiki.debian.org/lsusb > https://manpages.debian.org/man/0/lsusb > > The previous site had 0 as a wildcard for any section.
Thanks for pointing it out, this is fixed with https://github.com/Debian/debiman/commit/2517d8f6a070890469eb55d0533304a0da642f9e > >> While we were at it, we have restructured the paths so that we can >> serve all manpages, even those whose name conflicts with other binary >> packages (e.g. crontab(5) from cron, bcron or systemd-cron). Don’t >> worry: the old URLs are redirected correctly. > > Does this take into account that some manual pages are available only > on certain architectures? Or that some manual pages might differ Yes. > between architectures? No. Isn’t that a violation of the FHS (see http://www.pathname.com/fhs/pub/fhs-2.3.html#USRSHAREARCHITECTUREINDEPENDENTDATA) and Debian policy? > > In #264589 I wrote a patch for packages.debian.org to link to manual > pages from a few locations. Could you advise on any changes I should > make to the links in the patch? Cool! I wasn’t aware of this. https://github.com/Debian/debiman/blob/2517d8f6a070890469eb55d0533304a0da642f9e/internal/redirect/redirect_test.go#L237-L257 should give you a good overview of the URL schema which is now in use. Let me know if that answers your question or whether you need more details. > >> Furthermore, the design of the site has been updated and now includes >> navigation panels that allow quick access to the manpage in other >> Debian versions, other binary packages, other sections and other >> languages. Speaking of languages, the site serves manpages in all >> their available languages and respects your browser’s language when >> redirecting or following a cross-reference. > > I notice you force the URL to contain the package, version, language > and format, I would prefer normal URLs to not include either of those > and the defaults to be chosen via Accept-* if they are not part of the > URL. The links could then override them as needed. The language is already taken from the Accept-Language header if it’s not specified. Adding a plain text format and respecting the Accept header is on my TODO list. I guess it depends on your point of view what a “normal URL” really is. Maybe I also misunderstood your point — if so, please clarify. > > Would it be possible to titlecase the section names in the table of > contents and in the HTML? Why? In general, I’d like to stick with the conventions that are used for displaying manpages whenever a design choice is just about personal preference and not about enabling/preventing use-cases. > > Personally I much prefer non-monospaced text when reading > documentation. IIRC the debmans code did this better. It should be easy to configure a user style sheet to this purpose. Just configure font-family of the .mandoc class to your liking. > > The manual page converter seems to use line breaks rather than proper > paragraph tags. Could you report this issue upstream at http://mdocml.bsd.lv/ please? > > The Debian logo appears to be missing when I view the site in Tor > Browser on high security mode, due to the use of SVG with no fallback. Now tracked at https://github.com/Debian/debiman/issues/35 > > Non-truncated version numbers don't need the popup like truncated ones do. The truncation is done via CSS. I don’t know how to make the title attribute conditional on truncation. > > IIRC, according to the design principles of the current Debian > website design, the 'Index' link should not be present because the > link above it points at the same place. > > https://wiki.debian.org/KallesDesign Couldn’t find that bit on the wiki page. Can you point me to where it says that please? > > Can you change the top 'MANPAGES' link to 'Manual pages' instead? Any > other occurrences should change too (such as on the suite contents > pages). I thought that bit should equal the domain name. Is that incorrect? Do you have a reference for what it should contain? > > The suite contents pages contain a lot of whitespace on desktop > browsers. Just putting every manual page on one long line to be > wrapped by the browser might be better. I’m not sure. In practice, people are going to use the search function of their browser anyway. I feel that a long list is easier on the eye than a wall of text. > > If I press up in my browser, these URLs don't work or do the wrong thing: > > https://manpages.debian.org/jessie/manpages/ Where did you get this URL from? Is that used somewhere, or do you just think it would be nice if such a schema worked? > https://manpages.debian.org/jessie/ > https://manpages.debian.org/unstable/ Now tracked in https://github.com/Debian/debiman/issues/36 > >> Much like the Debian package tracker, manpages.debian.org includes >> packages from Debian oldstable, oldstable-backports, stable, >> stable-backports, testing and unstable. New manpages should make their >> way onto manpages.debian.org within a few hours. > > I'd really suggest using suite names by default instead of codenames > in the text of the versions section and in all URLs, with the > codenames also supported in URLs though. I considered this but arrived at the conclusion that a URL becomes more useful the longer it references the same document. I.e., if someone posts a link to a manpage, I’d like to make sure that — as long as said manpage is included in the distributions which we include — that URL points to precisely that same manpage. If you wish, you’re free to use the redirect functionality and always refer to suite names. > >> We’d love to hear your feedback and thoughts. Either contact us via an >> issue on https://github.com/Debian/debiman/issues/, or send an email >> to the debian-doc mailing list (see >> https://lists.debian.org/debian-doc/). > > It would be really nice if man-db had support for both manpages.d.o > and manpages.u.c. Can you elaborate on what you mean? > > Highlighting some more of the features on the front page might be useful. I don’t want to overwhelm people with an overly long front page. > > Is the rebuilding of new and updated manual pages triggered by Debian > mirror pushes? No. Due to the global view of manpages which is required for cross-referencing and navigation, a run is somewhat computationally costly (see https://github.com/Debian/debiman/blob/master/PERFORMANCE.md for wall-clock time numbers). Hence, we intend to do periodic runs, with a frequency of 1 or 2 hours. > > Are incoming.debian.org/archive.debian.org to be used as sources of > manual pages too? Can you explain the motivation for using incoming/archive please? > > I hope you aren't hard-coding any architecture info or codenames in > the source code or configs :) > > https://wiki.debian.org/SuitesAndReposExtension We currently do, unfortunately :). There are TODOs in the source to clean that up, but the site will keep working without update for the next 2 Debian releases (excluding stretch) even if we don’t get around to cleaning it up. Will amend the wiki page in a bit. > > You may want to mention this on debian-derivatives, to the > manpages.u.c maintainers and to the maintainers of other distros > manual page websites, some of them might like to use it, although Go > might put some of them off. I intended to contact the ubuntu people and other manpage repositories that I know of. Talking to derivatives is a good point, thanks. > > The wiki page needs to be rewritten now that debmans is dropped and > debiman is used on the site. > > https://wiki.debian.org/manpages.debian.org Yes, already on my TODO, thanks. -- Best regards, Michael