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

Bug#851885: Please add pseudopackage `manpages.debian.org'

[Ian Jackson]

Package: bugs.debian.org

Please add a pseudopackage for manpages.debian.org.

Its operator writes, Michael Stapelberg, writes:
> > [Michael:]
> [Ian Jackson:]
> > > 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.
> 
> 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.

Based on that I think the email for the pseudopackage should go to
debian-doc@l.d.o.

Michael, please let us know if that's not right.

Thanks,
Ian.

-- 
Ian Jackson    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  wrote:
> On Thu, Jan 19, 2017 at 1:23 AM, Michael Stapelberg wrote:
>
>> https://manpages.debian.org has been modernized! We have just launched
>> a major update to our manpage repository. What used to be served via a
>> CGI script is now a statically generated website, and therefore
>> blazingly fast.
>
> My dman shell function is now broken:
>
> dman () {
> w3m "https://manpages.debian.org/man0/$1;
> }
>
> The manpages.d.o URLs on these pages are broken:
>
> https://wiki.debian.org/AppArmor/Debug
> https://manpages.debian.org/man/0/aa-notify
>
> https://wiki.debian.org/lsusb
> https://manpages.debian.org/man/0/lsusb
>
> The previous site had 0 as a wildcard for any section.

Thanks for pointing it out, this is fixed with
https://github.com/Debian/debiman/commit/2517d8f6a070890469eb55d0533304a0da642f9e

>
>> While we were at it, we have restructured the paths so that we can
>> serve all manpages, even those whose name conflicts with other binary
>> packages (e.g. crontab(5) from cron, bcron or systemd-cron). Don’t
>> worry: the old URLs are redirected correctly.
>
> Does this take into account that some manual pages are available only
> on certain architectures? Or that some manual pages might differ

Yes.

> between architectures?

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

>
> In #264589 I wrote a patch for packages.debian.org to link to manual
> pages from a few locations. Could you advise on any changes I should
> make to the links in the patch?

Cool! I wasn’t aware of this.
https://github.com/Debian/debiman/blob/2517d8f6a070890469eb55d0533304a0da642f9e/internal/redirect/redirect_test.go#L237-L257
should give you a good overview of the URL schema which is now in use.
Let me know if that answers your question or whether you need more
details.

>
>> Furthermore, the design of the site has been updated and now includes
>> navigation panels that allow quick access to the manpage in other
>> Debian versions, other binary packages, other sections and other
>> languages. Speaking of languages, the site serves manpages in all
>> their available languages and respects your browser’s language when
>> redirecting or following a cross-reference.
>
> I notice you force the URL to contain the package, version, language
> and format, I would prefer normal URLs to not include either of those
> and the defaults to be chosen via Accept-* if they are not part of the
> URL. The links could then override them as needed.

The language is already taken from the Accept-Language header if it’s
not specified. Adding a plain text format and respecting the Accept
header is on my TODO list.

I guess it depends on your point of view what a “normal URL” really
is. Maybe I also misunderstood your point — if so, please clarify.

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

Why? In general, I’d like to stick with the conventions that are used
for displaying manpages whenever a design choice is just about
personal preference and not about enabling/preventing use-cases.

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

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

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

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

>
> The Debian logo appears to be missing when I view the site in Tor
> Browser on high security mode, due to the use of SVG with no fallback.

Now tracked at https://github.com/Debian/debiman/issues/35

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

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

>
> IIRC, according to the design principles  of the current Debian
> website design, the 'Index' link should not be present because the
> link above it points at the same place.
>
> https://wiki.debian.org/KallesDesign

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

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

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

>
> The suite contents pages contain a lot of whitespace on desktop
> browsers. Just putting every manual page on one long line to be
> wrapped by the browser might be better.

I’m not sure. In practice, people are going to use the search function
of their browser anyway. I feel that a long list is easier on the eye
than a wall of text.

>
> If I press up in my browser, these URLs 

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