Re: manpages.debian.org has been modernized!
On Thu, Jan 19, 2017 at 4:41 AM, Paul Wise <pabs@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
Reply to: