Re: Personal Git repositories on Alioth (was: manpages.debian.org has been modernized!)

[Paul Wise]

On Sat, Feb 18, 2017 at 9:39 AM, Ben Finney wrote:

> Does the resulting repository automatically get published on Alioth,
> managed by ‘cgit’ at a ‘anonscm.debian.org’ URL?

cgit doesn't do any management, it just publishes existing repos.

User repositories are available at URLs like these:

https://anonscm.debian.org/cgit/users/wouter/ipcfg.git/

-- 
bye,
pabs

https://wiki.debian.org/PaulWise

Re: manpages.debian.org has been modernized!

[Alexander Wirt]

On Wed, 08 Feb 2017, Wouter Verhelst wrote:

> On Thu, Jan 19, 2017 at 06:20:30PM +0100, Michael Stapelberg wrote:
> > Would a mirror of the git repository on alioth be sufficient? I had
> > planned to set that up, but didn’t get around to it yet. Any help with
> > that would be very welcome.
> 
> I realize you've already done so, but for future reference, this is
> ridiculously easy for anyone who's a Debian Developer or otherwise has
> an account on alioth:
> 
> ssh to git.debian.org, and run:
> 
> mkdir -p public_git/repo.git
> cd public_git/repo.git
> git init --bare
> 
> log out again; then, in your local repository, run:
> 
> git remote add --mirror debian git.debian.org:public_git/repo.git
> git push debian
> 
> you're done.
> 
> Alternatively, if you don't want to push all branches, drop the --mirror
> part on the 'git remote add' thing, and add a branch to every "git push
> debian" command. This works for all remotes btw, not just the alioth
> ones.
> 
> Personally, I tend to push my code to multiple git hosting services,
> because it's so simple to do.
or you can just tell me and I will add it to the mirror section :) on git.d.o

Alex
 

Re: manpages.debian.org has been modernized!

[Wouter Verhelst]

On Thu, Jan 19, 2017 at 06:20:30PM +0100, Michael Stapelberg wrote:
> Would a mirror of the git repository on alioth be sufficient? I had
> planned to set that up, but didn’t get around to it yet. Any help with
> that would be very welcome.

I realize you've already done so, but for future reference, this is
ridiculously easy for anyone who's a Debian Developer or otherwise has
an account on alioth:

ssh to git.debian.org, and run:

mkdir -p public_git/repo.git
cd public_git/repo.git
git init --bare

log out again; then, in your local repository, run:

git remote add --mirror debian git.debian.org:public_git/repo.git
git push debian

you're done.

Alternatively, if you don't want to push all branches, drop the --mirror
part on the 'git remote add' thing, and add a branch to every "git push
debian" command. This works for all remotes btw, not just the alioth
ones.

Personally, I tend to push my code to multiple git hosting services,
because it's so simple to do.

-- 
< ron> I mean, the main *practical* problem with C++, is there's like a dozen
   people in the world who think they really understand all of its rules,
   and pretty much all of them are just lying to themselves too.
 -- #debian-devel, OFTC, 2016-02-12

Re: manpages.debian.org has been modernized!

[Riku Voipio]

On Wed, Jan 18, 2017 at 06:23:16PM +0100, Michael Stapelberg wrote:
> We’d love to hear your feedback and thoughts. 

Thanks, really nice. This should motivate me to create manpages some
of my packages are missing. May https://manpages.debian.org/ rise
high in search engine rankings!

Riku

Re: manpages.debian.org has been modernized!

[Michael Biebl]

Hi Michael

Am 18.01.2017 um 18:23 schrieb Michael Stapelberg:
> https://manpages.debian.org has been modernized! We have just launched


Thanks a lot, this looks really nice.

One feature I'd like to see added is search as you type, like
tracker.d.o offers.


Regards,
Michael


-- 
Why is it that all of the instruments seeking intelligent life in the
universe are pointed away from Earth?



signature.asc
Description: OpenPGP digital signature

Re: manpages.debian.org has been modernized!

[Cyril Brulebois]

Hi,

Michael Stapelberg <stapelb...@debian.org> (2017-01-18):
> 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.

Many thanks, this looks like a very useful entry point for everyday
work, which would usually depend on having documentation for packages
that are not necessarily installed, sometimes having to switch between
several versions, etc.

Whatever is said in some subthreads: great work, thanks!


KiBi.


signature.asc
Description: Digital signature

Re: manpages.debian.org has been modernized!

[Craig Small]

On Thu, Jan 19, 2017 at 4:24 AM Michael Stapelberg 
wrote:

> 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 had a look at some of my manpages. They look good! It's a nice clean
appearance with doing sensible things like pulling out a TOC and
cross-references.


> 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
>
Being upstream for some packages and a Debian developer, I totally get the
thing about the github issues log versus the Debian BTS too.
Someone should fix that; but of course there are so many hours in the day.

 - Craig

-- 
Craig Small (@smallsees)   http://dropbear.xyz/ csmall at : enc.com.au
Debian GNU/Linux   http://www.debian.org/   csmall at : debian.org
GPG fingerprint:5D2F B320 B825 D939 04D2  0519 3938 F96B DF50 FEA5

Re: manpages.debian.org has been modernized!

[Michael Stapelberg]

Closing the loop on this part of the discussion:

https://anonscm.debian.org/cgit/users/stapelberg/debiman.git/ is the
mirror on alioth, to satisfy people who don’t want to interact with
GitHub for getting the source.

https://anonscm.debian.org/cgit/srv-manpages/debian-assets.git is the
canonical source of the debian-specific assets we use.

This should give you everything you need to reproduce byte-for-byte
identical output.

On Thu, Jan 19, 2017 at 6:20 PM, Michael Stapelberg
<stapelb...@debian.org> wrote:
> On Thu, Jan 19, 2017 at 4:43 PM, Ian Jackson
> <ijack...@chiark.greenend.org.uk> wrote:
>> Michael Stapelberg writes ("Re: manpages.debian.org has been modernized!"):
>>> On Wed, Jan 18, 2017 at 11:37 PM, Ian Jackson
>>> > Also, I think the exact running version of Debian services should be
>>> > publicly available.  And, unless this is made so easy that the service
>>> > operators don't have to think about it, it will always fall behind.
>>> > So I think this should be done automatically.
>>>
>>> All pages on manpages.debian.org already include the git revision at
>>> the bottom of the page, e.g.:
>>>
>>> debiman c17f615, see github.com/Debian/debiman
>>
>> mariner:~> curl -s 
>> 'https://manpages.debian.org/cgi-bin/man.cgi?query=make=0=0=Debian+8+jessie=html=en'
>>  | grep debiman
>> mariner:~>
>
> You’re querying the old software of manpages.debian.org which will be
> turned down soon.
>
>>
>>> Hence, you can already check out the exact running version. Is that
>>> not sufficient?
>>
>> I'm afraid not (even supposing that the lack of the commitid is just a
>> bug).  For a debian.org service, I would like to be able to check out
>> the running version without interacting with a proprietary online
>> service.
>
> Would a mirror of the git repository on alioth be sufficient? I had
> planned to set that up, but didn’t get around to it yet. Any help with
> that would be very welcome.
>
>>
>> Also, what stops (answer might be workflow, technology, whatever) an
>> operator who is in a hurry directly updating the running copy without
>> pushing to github ?
>
> People with the appropriate UNIX permissions (being part of the
> “manpages” group) can of course always circumvent any workflow or
> safe-guards which are put into place.
>
> Personally, my intention is that the workflow ends up such that the
> right thing happens. As the system is new and we’re just rolling it
> out now, things are still a bit in flux.
>
> In general, I hear your concern and would like to assure you that I am
> working towards the goal of anyone being able to reproduce the exact
> output that manpages.debian.org serves. If I fail in that endeavour
> within the next month or so, please feel free to poke me again. Until
> then, I’d like to ask you to allow us some time to get things settled.
>
>>
>> As I say, I don't want to impose more work on you because of my outre'
>> ethical views.  I would like to solve this problem by providing a
>> patch that causes debiman to copy its source and its git history to
>> its own output.  That way you would have to do nothing.
>
> To help me understand the implications of such a patch, can you point
> me to an existing implementation of such a patch in another service
> please?
>
>>
>>> > If we created a pseudopackage in the Debian bug system, would you use
>>> > it instead ?  It's one thing to use github as a generic git hosting
>>> > server but I really don't want us to be constructing our issue tracker
>>> > data in github's databases.
>>>
>>> I personally find the Debian bug system very uncomfortable to use. I
>>> will begrudgingly accept reports made via the BTS, as I do for the
>>> Debian packages I maintain. I don’t want to give up using GitHub’s
>>> issue tracker, though, for my convenience and the convenience of our
>>> users.
>>
>> Using github as well is up to you.  I won't try to talk you out of it.
>> But I think for a service in the .debian.org namespace, bugs should be
>> reportable without interacting with a proprietary web service.
>>
>> So thank you for agreeing to work with a system you don't find
>> comfortable.  You'll see that I have filed a bug against b.d.o
>> requesting the manpages.debian.org pseudopackage.
>>
>> Ian.
>>
>> --
>> Ian Jackson <ijack...@chiark.greenend.org.uk>   These opinions are my own.
>>
>> If I emailed you from an address @fyvzl.net or @evade.org.uk, that is
>> a private address which bypasses my fierce spamfilter.
>
>
>
> --
> Best regards,
> Michael



-- 
Best regards,
Michael

Re: manpages.debian.org has been modernized!

[Michael Stapelberg]

The  fallback has a drawback: it downloads both assets,
regardless of support.

Could you please verify whether the -based fallback works for
you? See https://people.debian.org/~stapelberg/fallback/i3.1.en.html
for a demo.

On Mon, Jan 23, 2017 at 10:02 AM, Michael Stapelberg
 wrote:
> I’m using SVG because it scales to whichever DPI your monitor might
> have. I’ll have a look at switching to  later, thanks.
>
> On Mon, Jan 23, 2017 at 10:00 AM, Paul Wise  wrote:
>> On Mon, 2017-01-23 at 08:47 +0100, Michael Stapelberg wrote:
>>
>>> Could you clarify how I can implement a fallback in a way that works
>>> for Tor Browser please?
>>
>> The  solution here appears to work:
>>
>> https://css-tricks.com/a-complete-guide-to-svg-fallbacks/#fallback-object
>>
>> In this case, the page constrains the SVG image to the same number of
>> pixels as the equivalent PNG image and the PNG image is a smaller
>> number of bytes and probably renders faster so I think just use PNG.
>>
>> --
>> bye,
>> pabs
>>
>> https://wiki.debian.org/PaulWise
>
>
>
> --
> Best regards,
> Michael



-- 
Best regards,
Michael

Re: manpages.debian.org has been modernized!

[Paul Wise]

On Wed, 2017-01-25 at 09:09 +0100, Michael Stapelberg wrote:

> Could you please verify whether the -based fallback works for
> you? See https://people.debian.org/~stapelberg/fallback/i3.1.en.html
> for a demo.

The SVG is downloaded but there is no fallback on high security.
I wouldn't worry about it, not an issue many folks will see.

-- 
bye,
pabs

https://wiki.debian.org/PaulWise


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

Re: manpages.debian.org has been modernized!

[Michael Stapelberg]

Makes sense to me.

On Tue, Jan 24, 2017 at 9:34 AM, Javier Fernandez-Sanguino
 wrote:
> On 23 January 2017 at 22:22, Michael Stapelberg 
> wrote:
>>
>> Thanks!
>>
>> I think we could put rewriterules in place to redirect hotlinks to the
>> cgi script to the correct place. I can take care of it if you want me
>> to.
>
>
>
> Thanks Michael. I suggest we wait some time (a month?), go then through the
> logs to see what is still using the old CGI and see if the effort is
> worthwhile. I am not sure how many users will still be using the the CGI
> script (maybe due to references in external sites) after the change.
>
> Best regards
>
> Javier
>



-- 
Best regards,
Michael

Re: manpages.debian.org has been modernized!

[Javier Fernandez-Sanguino]

On 23 January 2017 at 22:22, Michael Stapelberg 
wrote:

> Thanks!
>
> I think we could put rewriterules in place to redirect hotlinks to the
> cgi script to the correct place. I can take care of it if you want me
> to.



Thanks Michael. I suggest we wait some time (a month?), go then through the
logs to see what is still using the old CGI and see if the effort is
worthwhile. I am not sure how many users will still be using the the CGI
script (maybe due to references in external sites) after the change.

Best regards

Javier

Re: manpages.debian.org has been modernized!

[Michael Stapelberg]

Thanks!

I think we could put rewriterules in place to redirect hotlinks to the
cgi script to the correct place. I can take care of it if you want me
to.

On Mon, Jan 23, 2017 at 10:19 PM, Javier Fernandez-Sanguino
 wrote:
>
> On 20 January 2017 at 10:25, Javier Fernandez-Sanguino 
> wrote:
>>
>>
>>
>> This weekend I will modify the CGI so that it redirects to the new
>> (static) content for users that at some point still go to the old one. It
>> seems that the redirects get cached in the browser permanently because I
>> (wrongly) used 301 redirects instead of 302 in the previous configuration.
>> It also happens to me in my Android phone.
>
>
> This has now been implemented in the CGI script. Users are now pointed to
> the new interface.
>
> Regards
>
> Javier
>

-- 
Best regards,
Michael

Re: manpages.debian.org has been modernized!

[Javier Fernandez-Sanguino]

On 20 January 2017 at 10:25, Javier Fernandez-Sanguino 
wrote:

>
>
> This weekend I will modify the CGI so that it redirects to the new
> (static) content for users that at some point still go to the old one. It
> seems that the redirects get cached in the browser permanently because I
> (wrongly) used 301 redirects instead of 302 in the previous configuration.
> It also happens to me in my Android phone.
>

This has now been implemented in the CGI script. Users are now pointed to
the new interface.

Regards

Javier

Re: manpages.debian.org has been modernized!

[Michael Stapelberg]

I’m using SVG because it scales to whichever DPI your monitor might
have. I’ll have a look at switching to  later, thanks.

On Mon, Jan 23, 2017 at 10:00 AM, Paul Wise  wrote:
> On Mon, 2017-01-23 at 08:47 +0100, Michael Stapelberg wrote:
>
>> Could you clarify how I can implement a fallback in a way that works
>> for Tor Browser please?
>
> The  solution here appears to work:
>
> https://css-tricks.com/a-complete-guide-to-svg-fallbacks/#fallback-object
>
> In this case, the page constrains the SVG image to the same number of
> pixels as the equivalent PNG image and the PNG image is a smaller
> number of bytes and probably renders faster so I think just use PNG.
>
> --
> bye,
> pabs
>
> https://wiki.debian.org/PaulWise



-- 
Best regards,
Michael

Re: manpages.debian.org has been modernized!

[Paul Wise]

On Mon, 2017-01-23 at 08:47 +0100, Michael Stapelberg wrote:

> Could you clarify how I can implement a fallback in a way that works
> for Tor Browser please?

The  solution here appears to work:

https://css-tricks.com/a-complete-guide-to-svg-fallbacks/#fallback-object

In this case, the page constrains the SVG image to the same number of
pixels as the equivalent PNG image and the PNG image is a smaller
number of bytes and probably renders faster so I think just use PNG.

-- 
bye,
pabs

https://wiki.debian.org/PaulWise


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

Re: manpages.debian.org has been modernized!

[Javier Fernandez-Sanguino]

On 23 January 2017 at 08:49, Paul Wise  wrote:

> On Mon, 2017-01-23 at 08:45 +0100, Michael Stapelberg wrote:
>
> > What would be the best way to trigger on mirror pushes?
>
> I'm not sure about that, please ask #debian-mirrors
> or failing that #debian-admin, and or the lists.


Basicly, you give SSH access to an upstream mirror in the account used for
your tool (i.e. in our case 'manpages'). Instead of shell access, access
from the mirror to that account triggers running a task, which, in our
case, would run an archive update the archive.

I agree it is an interesting feature, but the previous service (CGI-based)
just triggered content updates through a cronjob, which was executed once
per month. I do not recall a complain from users mentioning it as "out of
date".

Best regards

Javier

Re: manpages.debian.org has been modernized!

[Michael Stapelberg]

On Thu, Jan 19, 2017 at 11:52 AM, Paul Wise  wrote:
> On Thu, 2017-01-19 at 09:35 +0100, Michael Stapelberg wrote:
>
>> To:   Paul Wise 
>
> 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. 

Re: manpages.debian.org has been modernized!

[Michael Stapelberg]

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.
>
>> 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?
>
> 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?
>
>> 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.
>
> Would it be possible to titlecase the section names in the table of
> contents and in the HTML?
>
> Personally I much prefer non-monospaced text when reading
> documentation. IIRC the debmans code did this better.
>
> The manual page converter seems to use line breaks rather than proper
> paragraph tags.
>
> 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.

I looked around for how to implement SVGs with fallback, and all
solutions either hard-code fallbacks for older browsers (not helpful
for this case) or require JavaScript (presumably not helpful/desired
in this case). See for example
http://callmenick.com/post/svg-fallback-with-png. Could you clarify
how I can implement a fallback in a way that works for Tor Browser
please?

>
> Non-truncated version numbers don't need the popup like truncated ones do.
>
> 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
>
> Can you change the top 'MANPAGES' link to 'Manual pages' instead? Any
> other occurrences should change too (such as on the suite contents
> pages).
>
> 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.
>
> If I press up in my browser, these URLs don't work or do the wrong thing:
>
> https://manpages.debian.org/jessie/manpages/
> https://manpages.debian.org/jessie/
> https://manpages.debian.org/unstable/
>
>> 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.
>
>> 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.
>
> Highlighting some more of the features on the front page might be useful.
>
> Is the rebuilding of new and updated manual pages triggered by Debian
>

Re: manpages.debian.org has been modernized!

[Paul Wise]

On Mon, 2017-01-23 at 08:45 +0100, Michael Stapelberg wrote:

> What would be the best way to trigger on mirror pushes?

I'm not sure about that, please ask #debian-mirrors
or failing that #debian-admin, and or the lists.

-- 
bye,
pabs

https://wiki.debian.org/PaulWise


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

Git hosting for code that provides Debian services (was: manpages.debian.org has been modernized!)

[Ben Finney]

Ian Jackson  writes:

> For a debian.org service, I would like to be able to check out the
> running version without interacting with a proprietary online service.

I have been looking at the GitLab instance hosted at FOSS Community
India's servers, . It's been working
fine for a few months.

Do the FOSS Community India people want us to make larger use of that
GitLab instance for general Debian code bases?

> Using github as well is up to you. I won't try to talk you out of it.
> But I think for a service in the .debian.org namespace, bugs should be
> reportable without interacting with a proprietary web service.

I believe the GitLab running at the above URL is entirely free software.

> So thank you for agreeing to work with a system you don't find
> comfortable. You'll see that I have filed a bug against b.d.o
> requesting the manpages.debian.org pseudopackage.

I would agree that the Debian BTS is important to maintain as the
primary bug reporting system for the Debian Project, in general. Even if
other platforms offer their own separate BTS, we strongly direct people
to the Debian BTS and it is important to have that as a first-class
venue for discussing bug reports.

-- 
 \  “In the long run, the utility of all non-Free software |
  `\  approaches zero. All non-Free software is a dead end.” —Mark |
_o__)Pilgrim, 2006 |
Ben Finney

Re: manpages.debian.org has been modernized!

[Peter Palfrader]

Ian Jackson schrieb am Donnerstag, dem 19. Jänner 2017:

> Michael Stapelberg writes ("Re: manpages.debian.org has been modernized!"):
> > On Thu, Jan 19, 2017 at 4:46 PM, Ian Jackson
> > > AFAICT this program is not packaged for Debian.
> > 
> > The program is packaged for Debian:
> > https://packages.debian.org/stretch/mandoc. I have uploaded a backport
> > which is currently pending in NEW.
> 
> Oh it's mandoc.  OK, sorry for misreading the web page.
> 
> Are you using the backport on the manpages.d.o server, then ?

You know, you could just check.. :)

-- 
|  .''`.   ** Debian **
  Peter Palfrader   | : :' :  The  universal
 https://www.palfrader.org/ | `. `'  Operating System
|   `-https://www.debian.org/

Re: manpages.debian.org has been modernized!

[Ian Jackson]

Michael Stapelberg writes ("Re: manpages.debian.org has been modernized!"):
> On Thu, Jan 19, 2017 at 4:46 PM, Ian Jackson
> > AFAICT this program is not packaged for Debian.
> 
> The program is packaged for Debian:
> https://packages.debian.org/stretch/mandoc. I have uploaded a backport
> which is currently pending in NEW.

Oh it's mandoc.  OK, sorry for misreading the web page.

Are you using the backport on the manpages.d.o server, then ?

> > (Are you using a version of mdocml running out of a git tree, or
> > what?  Are there other unpackaged dependencies?)
> 
> I am using a slightly patched version indeed. The patch will be sent
> upstream within the next few days.

The source for this patched version is in only available in NEW ?
(Ie only to DDs ?)

You see, I find this kind of chasing tiresome - whether I'm the user,
or the service operator.  I expect you do too.  Of course you're
probably hoping not to need to patch mandoc again.

How did you deploy the patched mandoc ?  I want to know this so I can
know how the source code can be automatically found and published.

Ian.

-- 
Ian Jackson <ijack...@chiark.greenend.org.uk>   These opinions are my own.

If I emailed you from an address @fyvzl.net or @evade.org.uk, that is
a private address which bypasses my fierce spamfilter.

Re: manpages.debian.org has been modernized!

[Ian Jackson]

Michael Stapelberg writes ("Re: manpages.debian.org has been modernized!"):
> On Thu, Jan 19, 2017 at 4:43 PM, Ian Jackson
> <ijack...@chiark.greenend.org.uk> wrote:
> > mariner:~> curl -s 
> > 'https://manpages.debian.org/cgi-bin/man.cgi?query=make=0=0=Debian+8+jessie=html=en'
> >  | grep debiman
> > mariner:~>
> 
> You’re querying the old software of manpages.debian.org which will be
> turned down soon.

I got that page as follows:

Type into my browser address bar
  https://manpages.debian.org/
This redirects to
  https://manpages.debian.org/cgi-bin/man.cgi
and then if I type in details I get a url like the above.

Hrm.

I just looked with HEAD(1) and I don't get the redirect.

Is it possible that there was previously a permanent redirect issued
from the toplevel URL to this cgi-bin one ?  I'm not sure how to
bypass such a thing.

> > Also, what stops (answer might be workflow, technology, whatever) an
> > operator who is in a hurry directly updating the running copy without
> > pushing to github ?
> 
> People with the appropriate UNIX permissions (being part of the
> “manpages” group) can of course always circumvent any workflow or
> safe-guards which are put into place.

Of course.  But the question is: is circumventing this ever the
easiest way to fix things ?

My experience of running online services is that in a crisis it can
sometimes be most convenient (fastest!) to use some kind of ad-hoc
deployment method, up to and including editing the running code
directly in a text editor.

Obviously there are risks to that kind of thing, but I want the
service operator to think about keeping the service running, and *not*
to have to worry about publishing source code.

> > As I say, I don't want to impose more work on you because of my outre'
> > ethical views.  I would like to solve this problem by providing a
> > patch that causes debiman to copy its source and its git history to
> > its own output.  That way you would have to do nothing.
> 
> To help me understand the implications of such a patch, can you point
> me to an existing implementation of such a patch in another service
> please?

dgit
  client
https://browse.dgit.debian.org/dgit.git/tree/dgit#n6316
(Currently broken in sid's dgit, 3.6, *sigh*, #851906)
  server side
https://browse.dgit.debian.org/dgit.git/tree/infra/dgit-ssh-dispatch#n167
  docs, search for `clone-dgit-repos-server'
https://manpages.debian.org/testing/dgit/dgit.1.en.html
  clone the server side for yourself
git+ssh://d...@push.dgit.debian.org/dgit/debian/repos/_dgit-repos-server.git
  NB this is the source to the special git server that `dgit push'
  talks to; browse.dgit.d.o is simply git repos published using cgit.

yarrg (yes, really, I have been known to play proprietary online
games, for which this is a fully Free helper service):
  intro docs for developers
http://yarrg.chiark.net/devel
  source code

http://www.chiark.greenend.org.uk/ucgi/~yarrgweb/git?p=ypp-sc-tools.web-live.git;a=blob;f=yarrg/web/source.tar.gz;h=0e47a83e38d755720427b9c453db6bed6cf33288;hb=HEAD

http://www.chiark.greenend.org.uk/ucgi/~yarrgweb/git?p=ypp-sc-tools.web-live.git;a=blob;f=yarrg/Commods.pm;h=5d0ffe29fd46b8dd7b06802655b84d132ec9f100;hb=HEAD#l493

Thanks,
Ian.

-- 
Ian Jackson <ijack...@chiark.greenend.org.uk>   These opinions are my own.

If I emailed you from an address @fyvzl.net or @evade.org.uk, that is
a private address which bypasses my fierce spamfilter.

Re: manpages.debian.org has been modernized!

[Michael Stapelberg]

Thanks for the report! This issue is now tracked at
https://github.com/Debian/debiman/issues/39

On Thu, Jan 19, 2017 at 4:14 PM, Baptiste Jammet <bapti...@mailoo.org> wrote:
> Hello,
>
> Le 18/01/2017 18:23, Michael Stapelberg a écrit :
>>
>> https://manpages.debian.org has been modernized!
>
> [...]
>>
>> We’d love to hear your feedback and thoughts.
>
>
> One little remark : the links in the table of content are inactives because
> spaces are not translated to underscores :
> EXIT STATUS
>
> And then :
> EXIT STATUS
>
> Thanks for this great upgrade of manpages.d.o
>
> Baptiste
>



-- 
Best regards,
Michael

Re: manpages.debian.org has been modernized!

[Michael Stapelberg]

On Thu, Jan 19, 2017 at 4:46 PM, Ian Jackson
<ijack...@chiark.greenend.org.uk> wrote:
> Michael Stapelberg writes ("Re: manpages.debian.org has been modernized!"):
>> On Thu, Jan 19, 2017 at 4:41 AM, Paul Wise <p...@debian.org> wrote:
>> > 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?
>
> AFAICT this program is not packaged for Debian.

The program is packaged for Debian:
https://packages.debian.org/stretch/mandoc. I have uploaded a backport
which is currently pending in NEW.

>
> I would like the actually-running source code for this too to be
> distributed by manpages.debian.org.  Would you accept a patch to do
> that ?
>
> (Are you using a version of mdocml running out of a git tree, or
> what?  Are there other unpackaged dependencies?)

I am using a slightly patched version indeed. The patch will be sent
upstream within the next few days.

-- 
Best regards,
Michael

Re: manpages.debian.org has been modernized!

[Michael Stapelberg]

On Thu, Jan 19, 2017 at 4:43 PM, Ian Jackson
<ijack...@chiark.greenend.org.uk> wrote:
> Michael Stapelberg writes ("Re: manpages.debian.org has been modernized!"):
>> On Wed, Jan 18, 2017 at 11:37 PM, Ian Jackson
>> > Also, I think the exact running version of Debian services should be
>> > publicly available.  And, unless this is made so easy that the service
>> > operators don't have to think about it, it will always fall behind.
>> > So I think this should be done automatically.
>>
>> All pages on manpages.debian.org already include the git revision at
>> the bottom of the page, e.g.:
>>
>> debiman c17f615, see github.com/Debian/debiman
>
> mariner:~> curl -s 
> 'https://manpages.debian.org/cgi-bin/man.cgi?query=make=0=0=Debian+8+jessie=html=en'
>  | grep debiman
> mariner:~>

You’re querying the old software of manpages.debian.org which will be
turned down soon.

>
>> Hence, you can already check out the exact running version. Is that
>> not sufficient?
>
> I'm afraid not (even supposing that the lack of the commitid is just a
> bug).  For a debian.org service, I would like to be able to check out
> the running version without interacting with a proprietary online
> service.

Would a mirror of the git repository on alioth be sufficient? I had
planned to set that up, but didn’t get around to it yet. Any help with
that would be very welcome.

>
> Also, what stops (answer might be workflow, technology, whatever) an
> operator who is in a hurry directly updating the running copy without
> pushing to github ?

People with the appropriate UNIX permissions (being part of the
“manpages” group) can of course always circumvent any workflow or
safe-guards which are put into place.

Personally, my intention is that the workflow ends up such that the
right thing happens. As the system is new and we’re just rolling it
out now, things are still a bit in flux.

In general, I hear your concern and would like to assure you that I am
working towards the goal of anyone being able to reproduce the exact
output that manpages.debian.org serves. If I fail in that endeavour
within the next month or so, please feel free to poke me again. Until
then, I’d like to ask you to allow us some time to get things settled.

>
> As I say, I don't want to impose more work on you because of my outre'
> ethical views.  I would like to solve this problem by providing a
> patch that causes debiman to copy its source and its git history to
> its own output.  That way you would have to do nothing.

To help me understand the implications of such a patch, can you point
me to an existing implementation of such a patch in another service
please?

>
>> > If we created a pseudopackage in the Debian bug system, would you use
>> > it instead ?  It's one thing to use github as a generic git hosting
>> > server but I really don't want us to be constructing our issue tracker
>> > data in github's databases.
>>
>> I personally find the Debian bug system very uncomfortable to use. I
>> will begrudgingly accept reports made via the BTS, as I do for the
>> Debian packages I maintain. I don’t want to give up using GitHub’s
>> issue tracker, though, for my convenience and the convenience of our
>> users.
>
> Using github as well is up to you.  I won't try to talk you out of it.
> But I think for a service in the .debian.org namespace, bugs should be
> reportable without interacting with a proprietary web service.
>
> So thank you for agreeing to work with a system you don't find
> comfortable.  You'll see that I have filed a bug against b.d.o
> requesting the manpages.debian.org pseudopackage.
>
> Ian.
>
> --
> Ian Jackson <ijack...@chiark.greenend.org.uk>   These opinions are my own.
>
> If I emailed you from an address @fyvzl.net or @evade.org.uk, that is
> a private address which bypasses my fierce spamfilter.



-- 
Best regards,
Michael

Re: manpages.debian.org has been modernized!

[Ian Jackson]

Michael Stapelberg writes ("Re: manpages.debian.org has been modernized!"):
> On Thu, Jan 19, 2017 at 4:41 AM, Paul Wise <p...@debian.org> wrote:
> > 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?

AFAICT this program is not packaged for Debian.

I would like the actually-running source code for this too to be
distributed by manpages.debian.org.  Would you accept a patch to do
that ?

(Are you using a version of mdocml running out of a git tree, or
what?  Are there other unpackaged dependencies?)

Thanks,
Ian.

-- 
Ian Jackson <ijack...@chiark.greenend.org.uk>   These opinions are my own.

If I emailed you from an address @fyvzl.net or @evade.org.uk, that is
a private address which bypasses my fierce spamfilter.

Re: manpages.debian.org has been modernized!

[Ian Jackson]

Michael Stapelberg writes ("Re: manpages.debian.org has been modernized!"):
> On Wed, Jan 18, 2017 at 11:37 PM, Ian Jackson
> > Also, I think the exact running version of Debian services should be
> > publicly available.  And, unless this is made so easy that the service
> > operators don't have to think about it, it will always fall behind.
> > So I think this should be done automatically.
> 
> All pages on manpages.debian.org already include the git revision at
> the bottom of the page, e.g.:
> 
> debiman c17f615, see github.com/Debian/debiman

mariner:~> curl -s 
'https://manpages.debian.org/cgi-bin/man.cgi?query=make=0=0=Debian+8+jessie=html=en'
 | grep debiman
mariner:~>

> Hence, you can already check out the exact running version. Is that
> not sufficient?

I'm afraid not (even supposing that the lack of the commitid is just a
bug).  For a debian.org service, I would like to be able to check out
the running version without interacting with a proprietary online
service.

Also, what stops (answer might be workflow, technology, whatever) an
operator who is in a hurry directly updating the running copy without
pushing to github ?

As I say, I don't want to impose more work on you because of my outre'
ethical views.  I would like to solve this problem by providing a
patch that causes debiman to copy its source and its git history to
its own output.  That way you would have to do nothing.

> > If we created a pseudopackage in the Debian bug system, would you use
> > it instead ?  It's one thing to use github as a generic git hosting
> > server but I really don't want us to be constructing our issue tracker
> > data in github's databases.
> 
> I personally find the Debian bug system very uncomfortable to use. I
> will begrudgingly accept reports made via the BTS, as I do for the
> Debian packages I maintain. I don’t want to give up using GitHub’s
> issue tracker, though, for my convenience and the convenience of our
> users.

Using github as well is up to you.  I won't try to talk you out of it.
But I think for a service in the .debian.org namespace, bugs should be
reportable without interacting with a proprietary web service.

So thank you for agreeing to work with a system you don't find
comfortable.  You'll see that I have filed a bug against b.d.o
requesting the manpages.debian.org pseudopackage.

Ian.

-- 
Ian Jackson <ijack...@chiark.greenend.org.uk>   These opinions are my own.

If I emailed you from an address @fyvzl.net or @evade.org.uk, that is
a private address which bypasses my fierce spamfilter.

Re: manpages.debian.org has been modernized!

[Baptiste Jammet]

Hello,

Le 18/01/2017 18:23, Michael Stapelberg a écrit :

https://manpages.debian.org has been modernized!

[...]

We’d love to hear your feedback and thoughts.


One little remark : the links in the table of content are inactives 
because spaces are not translated to underscores :
EXIT 
STATUS


And then :
EXIT STATUS

Thanks for this great upgrade of manpages.d.o

Baptiste

Re: manpages.debian.org has been modernized!

[Paul Wise]

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

> To:   Paul Wise 

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.

> 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


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

Re: manpages.debian.org has been modernized!

[Michael Stapelberg]

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 pa

Re: manpages.debian.org has been modernized!

[Michael Stapelberg]

On Thu, Jan 19, 2017 at 5:33 AM, Boyuan Yang <073p...@gmail.com> wrote:
> [ Dropping debian-devel -- this is a bug-report email ]
>
>
>
> 在 2017年1月18日星期三 SGT 下午6:23:16，Michael Stapelberg 写道：
>
>> 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.
>
>>
>
>> 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/).
>
>
>
> Thanks for your work! The new website is indeed a great leap forward.
>
>
>
> That said, there are still several minor problems with the rendering of man
> pages:
>
>
>
> 1. When the man page is a stub and cannot fit the full width of 80 chars,
> the page would be somehow ugly. See the example at
> https://manpages.debian.org/jessie/manpages-zh/intro.1.zh_CN.html when all
> lines are short and the navigation div just occupied the middle of the page.

Thanks for the example. Tracking this in
https://github.com/Debian/debiman/issues/22

>
>
>
> 2. Several strange adjustment characters appeared in man pages generated by
> po4a. Take a look at the SYNOPSIS section of
> https://manpages.debian.org/testing/manpages-zh/test.1.zh_CN.html and
> /usr/share/man/zh_CN/man1/test.1.gz (provided by manpages-zh).

This is a mandoc rendering issue:

$ curl -s https://manpages.debian.org/testing/manpages-zh/test.1.zh_CN.gz
| mandoc /dev/stdin | head
TEST(1)用户命令TEST(1)



 名 称
   test - 检查文件类型并比较值

 概 述
   test ,表达式/
   test

$ curl -s https://manpages.debian.org/testing/manpages-zh/test.1.zh_CN.gz
| man /dev/stdin | head
TEST(1)
用户命令
TEST(1)

名
   test - 检查文件类型并比较值

概
   test 表达式
   test

   [ 表达式 ]

Mandoc upstream is http://mdocml.bsd.lv/. Would you like to report the
issue there yourself, or would you prefer if I did?


-- 
Best regards,
Michael

Re: manpages.debian.org has been modernized!

[Boyuan Yang]

[ Dropping debian-devel -- this is a bug-report email ]

在 2017年1月18日星期三 SGT 下午6:23:16，Michael Stapelberg 写道：
> 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.
> 
> 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/).

Thanks for your work! The new website is indeed a great leap forward.

That said, there are still several minor problems with the rendering of man 
pages:

1. When the man page is a stub and cannot fit the full width of 80 chars, the 
page would be 
somehow ugly. See the example at 
https://manpages.debian.org/jessie/manpages-zh/intro.
1.zh_CN.html when all lines are short and the navigation div just occupied the 
middle of the 
page.

2. Several strange adjustment characters appeared in man pages generated by 
po4a. Take a 
look at the SYNOPSIS section of 
https://manpages.debian.org/testing/manpages-zh/test.
1.zh_CN.html and /usr/share/man/zh_CN/man1/test.1.gz (provided by manpages-zh).

Thanks,
Boyuan Yang


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

Re: manpages.debian.org has been modernized!

[Paul Wise]

On Thu, Jan 19, 2017 at 6:37 AM, Ian Jackson wrote:

> As you might expect, I'm uncomfortable about the use of the
> proprietary github service for this.  I realise that we don't
> necessarily have entirely comparable alternatives, but Free Software
> needs free tools.[1]

Agreed for both bugs and contribution mechanisms.
Same goes for the codesearch.d.n service too.

-- 
bye,
pabs

https://wiki.debian.org/PaulWise

Re: manpages.debian.org has been modernized!

[Paul Wise]

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.

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

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?

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

Would it be possible to titlecase the section names in the table of
contents and in the HTML?

Personally I much prefer non-monospaced text when reading
documentation. IIRC the debmans code did this better.

The manual page converter seems to use line breaks rather than proper
paragraph tags.

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.

Non-truncated version numbers don't need the popup like truncated ones do.

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

Can you change the top 'MANPAGES' link to 'Manual pages' instead? Any
other occurrences should change too (such as on the suite contents
pages).

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.

If I press up in my browser, these URLs don't work or do the wrong thing:

https://manpages.debian.org/jessie/manpages/
https://manpages.debian.org/jessie/
https://manpages.debian.org/unstable/

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

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

Highlighting some more of the features on the front page might be useful.

Is the rebuilding of new and updated manual pages triggered by Debian
mirror pushes?

Are incoming.debian.org/archive.debian.org to be used as sources of
manual pages too?

I hope you aren't hard-coding any architecture info or codenames in
the source code or configs :)

https://wiki.debian.org/SuitesAndReposExtension

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.

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

-- 
bye,
pabs

https://wiki.debian.org/PaulWise

Re: manpages.debian.org has been modernized!

[Henrique de Moraes Holschuh]

On Wed, 18 Jan 2017, 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.

Oooh, nice! A big thank you for all involved!

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

Maybe you could consider adding the manpages from packages in contrib as
well?  Unlike non-free, the licenses in contrib are all compatible with
the DFSG, so they must not have any license restrictions that would get
in the way...

-- 
  Henrique Holschuh

Re: manpages.debian.org has been modernized!

[Ian Jackson]

Michael Stapelberg writes ("manpages.debian.org has been modernized!"):
> https://manpages.debian.org has been modernized!

Awesome!  Thanks to everyone.

> https://github.com/Debian/debiman. In case you would like to use it to
> run a similar manpage repository (or convert your existing manpage
> repository to it), we’d love to help you out; just send an email to
> stapelberg AT debian DOT org.

As you might expect, I'm uncomfortable about the use of the
proprietary github service for this.  I realise that we don't
necessarily have entirely comparable alternatives, but Free Software
needs free tools.[1]

Also, I think the exact running version of Debian services should be
publicly available.  And, unless this is made so easy that the service
operators don't have to think about it, it will always fall behind.
So I think this should be done automatically.

Would you accept a patch to make debiman copy its own source code,
including git history, to its output ?  Then there could be a `source
code for this manpage generator' link on each page, or maybe in the
information page.  I have done this for a few programs I have written
and it's surprisingly easy.  When it's done, you will always be
publishing your own up to date source code.

Speaking of the information page, if you click on the info links you
get this
  https://manpages.debian.org/cgi-bin/man.cgi?query=info.html
which seems out of date.

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

If we created a pseudopackage in the Debian bug system, would you use
it instead ?  It's one thing to use github as a generic git hosting
server but I really don't want us to be constructing our issue tracker
data in github's databases.

Regards,
Ian.

[1] https://mako.cc/writing/hill-free_tools.html
  As true now as it was in 2010.

-- 
Ian Jackson <ijack...@chiark.greenend.org.uk>   These opinions are my own.

If I emailed you from an address @fyvzl.net or @evade.org.uk, that is
a private address which bypasses my fierce spamfilter.

Re: manpages.debian.org has been modernized!

[W. Martin Borgert]

On 2017-01-18 18:23, Michael Stapelberg wrote:
> https://manpages.debian.org has been modernized!

Congrats and thanks! I like it!

Re: manpages.debian.org has been modernized!

[Michael Stapelberg]

On Wed, Jan 18, 2017 at 8:48 PM, Brian Potkin <br...@copernicus.org.uk> wrote:
> On Wed 18 Jan 2017 at 18:23:16 +0100, 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.
>>
>> 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.
>>
>> 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.
>>
>> 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.
>>
>> The generator program (“debiman”) is open source and can be found at
>> https://github.com/Debian/debiman. In case you would like to use it to
>> run a similar manpage repository (or convert your existing manpage
>> repository to it), we’d love to help you out; just send an email to
>> stapelberg AT debian DOT org.
>>
>> This effort is standing on the shoulders of giants: check out
>> https://manpages.debian.org/about.html for a list of people we thank.
>>
>> 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/).
>
> Very nice. And as you say - blazingly fast. Thank you very much for the work
> put into it.

I’m very glad (all of you) like the result :).

>
> Have you considered the cultural and linguistic implications and the image of
> the Debian Project presented by the page which is served when a man page is 
> not
> found.
>
> "Sorry, the manpage “driverless” was not found! Did you spell it correctly?" 
> is
> informative and easily understandable by someone with a basic knowledge of
> English. It is can be acted on. The additional "Oh geez!" doesn't seem to add
> anything at all to resolving the issue. Maybe it gets translated into a 
> helpful
> message in other languages? (Is it intended to raise a smile and keep one's
> spirits up in the face of failure?)

It does not get translated. In general, the user interface is english
only for now. And yes, the intent was for the program to come off as
playful and a bit quirky, so as to amuse you even though we just had
to present you with an error page.

>
> My preference would be to substitute something like "Oh, bugger!", "Oh,
> merde!", "Oh, crap!" "Oh, damn!", "Oh, sod!", "Oh, gosh!" or "OMG!". On the
> whole I'd remove the phrase to allow the message to stand by itself and get
> through.

I’ve replaced it with the more factual “Manpage not found”.

> BTW, my speling is generally good. The driverless man page is in experimental
> only.

We don’t currently process experimental. Maybe we should? I’ve filed
https://github.com/Debian/debiman/issues/23 to track this.

-- 
Best regards,
Michael

Re: manpages.debian.org has been modernized!

[Brian Potkin]

On Wed 18 Jan 2017 at 18:23:16 +0100, 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.
> 
> 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.
> 
> 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.
> 
> 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.
> 
> The generator program (“debiman”) is open source and can be found at
> https://github.com/Debian/debiman. In case you would like to use it to
> run a similar manpage repository (or convert your existing manpage
> repository to it), we’d love to help you out; just send an email to
> stapelberg AT debian DOT org.
> 
> This effort is standing on the shoulders of giants: check out
> https://manpages.debian.org/about.html for a list of people we thank.
> 
> 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/).

Very nice. And as you say - blazingly fast. Thank you very much for the work
put into it.

Have you considered the cultural and linguistic implications and the image of
the Debian Project presented by the page which is served when a man page is not
found.

"Sorry, the manpage “driverless” was not found! Did you spell it correctly?" is
informative and easily understandable by someone with a basic knowledge of
English. It is can be acted on. The additional "Oh geez!" doesn't seem to add
anything at all to resolving the issue. Maybe it gets translated into a helpful
message in other languages? (Is it intended to raise a smile and keep one's
spirits up in the face of failure?)

My preference would be to substitute something like "Oh, bugger!", "Oh,
merde!", "Oh, crap!" "Oh, damn!", "Oh, sod!", "Oh, gosh!" or "OMG!". On the
whole I'd remove the phrase to allow the message to stand by itself and get
through.

BTW, my speling is generally good. The driverless man page is in experimental
only.

-- 
Brian.

Re: manpages.debian.org has been modernized!

[Beatrice Torracca]

On mercoledì 18 gennaio 2017, at 18:23 +0100, Michael Stapelberg wrote:

Hi!

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

I tried a couple of "random" pages and indeed it was very fast.

> 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 like it a lot. Indeed it showed me the Italian version, but it was
very easy to switch to the English one.

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

I am just writing to say thanks to all those who worked on this new
and improved manpages.debian.org. You did a very useful job.

Thanks,

beatrice

Re: manpages.debian.org has been modernized!

[Bob Bernstein]

Huzzahs! Congrats!

What an enormous piece of work you have brought to wonderful 
fruition!


Cigars all 'round!

--
IMPORTANT: This email is intended for the use of the individual
addressee(s) named above and may contain information that is
confidential, privileged or unsuitable for overly sensitive
persons with low self-esteem, no sense of humour or irrational
metaphysical beliefs.

manpages.debian.org has been modernized!

[Michael Stapelberg]

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.

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.

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.

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.

The generator program (“debiman”) is open source and can be found at
https://github.com/Debian/debiman. In case you would like to use it to
run a similar manpage repository (or convert your existing manpage
repository to it), we’d love to help you out; just send an email to
stapelberg AT debian DOT org.

This effort is standing on the shoulders of giants: check out
https://manpages.debian.org/about.html for a list of people we thank.

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

-- 
Best regards,
Michael