search

Debian / debiman

debiman generates a static manpage HTML repository out of a Debian archive
Apache License 2.0
189 stars 46 forks source link

add a note where to report problems #61

Closed nmartensen closed 7 years ago

nmartensen commented 7 years ago

When reading a manpage, it may happen that readers will notice problems. These might be related to broken manpage display, but can also be errors in the content like wrong descriptions or simple typos.

It would be nice to have a hint on each page on where/how to report problems.

stapelberg commented 7 years ago

There are 3 different places where problems might need to be reported:

  1. If the manpage renders correctly in some manpage viewers, but not on manpages.debian.org, this might likely be a limitation/bug with mdocml (the renderer we use). Report at mdocml.
  2. If the manpage contains wrong content, and was added by the Debian package maintainer, report at the Debian bug tracker.
  3. If the manpage contains wrong content and comes from the upstream software, report at the upstream bug tracker.

I’m happy to add this information to our documentation (I think we might have enough questions to re-instate the FAQ section on manpages.debian.org by now), but I don’t see how we could distinguish the cases from each other, i.e. we can’t distill it into a simple “click here to report a problem” link.

What do you think?

nmartensen commented 7 years ago

"Noticed a problem? Please check our FAQ." - I like this, good idea.

anarcat commented 7 years ago

maybe the FAQ link could just point to the wiki that way anyone could edit it easily? IIRC, the site-specific assets are not here, and it may be confusing for people to edit/report issues against the FAQ...

anarcat commented 7 years ago

i created a "faq" branch on the debian-assets repository:

https://anonscm.debian.org/git/srv-manpages/debian-assets.git/log/?h=faq

i haven't merged it because i'm not sure it was actually wanted here. let me know if i should just merge/push the result. there are other issues solved by that branch too, btw. see #76 and #52.

stapelberg commented 7 years ago

See my reply in https://github.com/Debian/debiman/issues/76#issuecomment-298753795

anarcat commented 7 years ago

i have merged the faq branch as is, which should clearly document how to do things here. this will show up once a full rebuild is triggered, see #76 for followup.

this issue, therefore, should be closed.