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

Re: manpages.debian.org has been modernized!

On Thu, 2017-01-19 at 09:35 +0100, Michael Stapelberg wrote:

> To:	Paul Wise <pabs@debian.org>

I'm subscribed :)

> No. Isn’t that a violation of the FHS (see
> http://www.pathname.com/fhs/pub/fhs-2.3.html#USRSHAREARCHITECTUREINDEPENDENTDATA)
> and Debian policy?

I suppose. I don't think we test for it though?

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

Thanks for that.

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

I guess I am talking about the URL you get from the jump redirector
or the future Apache based system.

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

A website is a different context than terminal manual page viewing.
The usual convention for headings on the web is either "Title Case" or
"Title case". Also, "UPPER CASE" is commonly thought of as shouting
on the web. Also, the web way looks less jarring in a web browser.

> It should be easy to configure a user style sheet to this purpose.
> Just configure font-family of the .mandoc class to your liking.

I think that non-monospace should be the default for the same reasons
we should not have upper-case section titles.

> Could you report this issue upstream at http://mdocml.bsd.lv/ please?

I'll leave that to someone more familiar with the project.

> The truncation is done via CSS. I don’t know how to make the title
> attribute conditional on truncation.

Interesting, me either.

> Couldn’t find that bit on the wiki page. Can you point me to where it
> says that please?

I may have misremembered. Either way it is pointless to have 2 links.

Also, it would be good if the index page didn't say 'index' in the page
title, that is jargon that isn't useful.

> I thought that bit should equal the domain name. Is that incorrect?
> Do you have a reference for what it should contain?

Not necessarily, for example lists.d.o uses 'mailing lists':


'manual pages' is slightly less jargony too.

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

Hmm, perhaps. What about one line per package name?

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

I stripped of the end component since URLs are usually hierarchical.

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

Hmm, ok.

Using suite names means that the URLs last longer.
Codenames disappear after a bunch of years.

> Can you elaborate on what you mean?

$ man foo
No manual entry for foo
Download and view manual page for foo? (Y/n)

> I don’t want to overwhelm people with an overly long front page.

Fair enough.

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

IIRC that is 6 times shorter than the archive update frequency :)
IIRC mirror push frequency is the same as archive update frequency.
It is pretty pointless to run it more often than those.
Triggering it on mirror pushes would mean that the second the local
mirror is finished updating, the new manual page generation starts.

> Can you explain the motivation for using incoming/archive please?

Using incoming means that new manual pages are available sooner.
Using archive means that I can still look up old manual pages.

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

Ick, thanks for the wiki edits.

> I intended to contact the ubuntu people and other manpage repositories
> that I know of. Talking to derivatives is a good point, thanks.

Great, thanks.

> Yes, already on my TODO, thanks.




Attachment: signature.asc
Description: This is a digitally signed message part

Reply to: