[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

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

>> 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


> between architectures?

No. Isn’t that a violation of the FHS (see
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.
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

>> 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

>> 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,

Reply to: