Re: manpages.debian.org has been modernized!
On Thu, Jan 19, 2017 at 11:52 AM, Paul Wise <pabs@debian.org> wrote:
> 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':
>
> https://lists.debian.org/
>
> '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.
What would be the best way to trigger on mirror pushes?
>
>> 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.
>
> Cool.
>
> --
> bye,
> pabs
>
> https://wiki.debian.org/PaulWise
--
Best regards,
Michael
Reply to: