Bug#850171: Recommend that manpages contain an EXAMPLES section

2018-11-04 Thread Russ Allbery 
Mattia Rizzolo  writes:

> What I mean is: if there is really enough people wanting this change by
> all means do it, but 1. make the wording clear that is really optional
> (in this view, I see "recommended" as too strong a word) and 2. I really
> hope lintian won't start bothering for this.

Maybe https://wiki.debian.org/UpstreamGuide would be a better place for
this?  Currently, it doesn't even explicitly recommend that upstream
provide man pages.

-- 
Russ Allbery (r...@debian.org)

Bug#850171: Recommend that manpages contain an EXAMPLES section

2018-11-04 Thread Holger Levsen 
On Sun, Nov 04, 2018 at 10:28:31AM +0100, Mattia Rizzolo wrote:
> I'm wary of one thing: I don't really want to be bothered by this.

same here.

> Going around patching upstream's manpages to add an EXAMPLE section is
> totally busywork, not mention possibly even hard to do for all the
> autogenerated manpages.
> What I mean is: if there is really enough people wanting this change by
> all means do it, but 1. make the wording clear that is really optional
> (in this view, I see "recommended" as too strong a word) and 2. I really
> hope lintian won't start bothering for this.

totally agreed.

manpages are great for cli software but for lots of desktop software
most of its users (and developers?) dont even know what manpages are, or
how to use them. thus I consider current policy (which treats the
absence of a manpage for *every* program, utility, and function in
Debian as a bug) already to be too strong today.


-- 
cheers,
Holger

---
   holger@(debian|reproducible-builds|layer-acht).org
   PGP fingerprint: B8BF 5413 7B09 D35C F026 FE9D 091A B856 069A AA1C


signature.asc
Description: PGP signature

Processed: fix bug titles

2018-11-04 Thread Debian Bug Tracking System 
Processing commands for cont...@bugs.debian.org:

> retitle 911166 gtksourceview2: Do not release with Bullseye
Bug #911166 [src:gtksourceview2] gtksourceview2: Do not release with Buster
Changed Bug title to 'gtksourceview2: Do not release with Bullseye' from 
'gtksourceview2: Do not release with Buster'.
> retitle 911165 debian-policy: drop requirement to ship sysvinit init script 
> with same name
Bug #911165 [debian-policy] gtksourceview2: Do not release with Bullseye
Changed Bug title to 'debian-policy: drop requirement to ship sysvinit init 
script with same name' from 'gtksourceview2: Do not release with Bullseye'.
> thanks
Stopping processing here.

Please contact me if you need assistance.
-- 
911165: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=911165
911166: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=911166
Debian Bug Tracking System
Contact ow...@bugs.debian.org with problems

Bug#690750: Broken links in developers-reference as published on the Debian's website

2018-11-04 Thread Holger Wansing 
Hi,

Lev Lamberov  wrote:
> Hi Holger,
> 
> thanks for your attention to the bug report, but my report was about a
> different issue. Let me explain.

When looking into all this, it's even more complicated ...

> First, let's take a look at developers-reference as it pubished on the
> Debian's website. Say, in English [web-en]. It incorrectly links to
> translations as index.{fr,de,it,ru,jp}.en.html, such files do not exist.
> Any other translation, say, French [web-fr] links to translations as
> index.{de,it,ru,jp}.fr.html, such files do not exist.
> 
> [web-en] https://www.debian.org/doc/manuals/developers-reference/index.en.html
> 
> [web-fr] https://www.debian.org/doc/manuals/developers-reference/index.fr.html

... since there are links on the website which work, and others do not:

On https://www.debian.org/doc/devel-manuals#devref (on the wegpage itself)
all links are correct and working.
However, when going into the document itself under for example
https://www.debian.org/doc/manuals/developers-reference/index.en.html
we can find links to
https://www.debian.org/doc/manuals/developers-reference/index.fr.en.html
https://www.debian.org/doc/manuals/developers-reference/index.de.en.html
and so on. So re-writing the links inside the document does not work correctly,
while the ones on the wegpages itself are fine.


> Second, let's take a look at developers-reference package. All links
> there are correct, that is in _any_ language links point to
> index.{fr,de,it,ru,jp}.html.

That might be correct so far.
However, if you install those packages on your local machine (let's say the
english and the french package), the links inside that documents do not
work:
when you open the english document locally, the link to the german version
is file:///usr/share/doc/developers-reference/index.de.html
however that file does not exist, it is stored as
usr/share/doc/developers-reference-de/index.html


> Third, let's take a look at developers-reference source code. In English
> we currently have as follows:
> 
> 
> If you want to print this reference, you should use the  url="developers-reference.pdf">pdf version.  This page is also
> available in French,  url="index.de.html">German,  url="index.it.html">Italian,  url="index.ru.html">Russian, and  url="index.ja.html">Japanese.
> 
> 




Proposal: maybe the easiest way to make all variants (view via debian.org
and opened locally) work correctly, would be to change it this way:

"This page is also available in
https://www.debian.org/doc/devel-manuals#devref;>French, German, 
Italian, Russian, and Japanese."

since the links on that page are fine and can be linked from everywhere
with one single static link.
Of course, there are still some corner cases which do not work (for example, 
when you have the packages installed locally, you cannot switch from the 
local english to the local german version via that links, and when you
have no internet connection, you also get an irritating situation), but most 
usecases should be fine, and it would be an improvement compared to the 
current situation, where all links do not work!

Would fix #690750 and #912724.


Comments?

Holger


-- 

Created with Sylpheed 3.5.1 under 
D E B I A N   L I N U X   9   " S T R E T C H " .

Registered Linux User #311290 - https://linuxcounter.net/

Bug#912724: Broken links in developers-reference as published on the Debian's website

2018-11-04 Thread Holger Wansing 
Control: reassign 912724 www.debian.org

Lev Lamberov  wrote:
> Hi Holger,
> 
> thanks for your attention to the bug report, but my report was about a
> different issue. Let me explain.
> 
[]
> 
> Let me stress that my report is _not_ about links to English, or links
> in English. It is about _broken_ links in _any_ developers-reference as
> published on the Debian's website. So, my bug report is about
> www.debian.org, not developers-reference. Please, reconsider it and
> reassign #912724 to www.debian.org.

Yes, you are right. I did not read your report careful enough. Sorry.
Reassigning back to www.debian.org


Holger

-- 

Created with Sylpheed 3.5.1 under 
D E B I A N   L I N U X   9   " S T R E T C H " .

Registered Linux User #311290 - https://linuxcounter.net/

Processed: Re: Broken links in developers-reference as published on the Debian's website

2018-11-04 Thread Debian Bug Tracking System 
Processing control commands:

> reassign 912724 www.debian.org
Bug #912724 [developers-reference] www.debian.org: wrong links to translations 
of "Debian Developer's Reference"
Bug reassigned from package 'developers-reference' to 'www.debian.org'.
Ignoring request to alter found versions of bug #912724 to the same values 
previously set
Ignoring request to alter fixed versions of bug #912724 to the same values 
previously set

-- 
912724: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=912724
Debian Bug Tracking System
Contact ow...@bugs.debian.org with problems

Bug#850171: Recommend that manpages contain an EXAMPLES section

2018-11-04 Thread Mattia Rizzolo 
On Sat, Nov 03, 2018 at 02:00:51PM -0700, Sean Whitton wrote:
> +It is recommended that manual pages contain an EXAMPLES section,
> +containing working syntax that uses the functionality documented by
> +the manual page.  For example, command-line invocations of a utility
> +for some of its standard usages, or an example call to an API
> +function.

I'm wary of one thing: I don't really want to be bothered by this.
Going around patching upstream's manpages to add an EXAMPLE section is
totally busywork, not mention possibly even hard to do for all the
autogenerated manpages.
What I mean is: if there is really enough people wanting this change by
all means do it, but 1. make the wording clear that is really optional
(in this view, I see "recommended" as too strong a word) and 2. I really
hope lintian won't start bothering for this.

-- 
regards,
Mattia Rizzolo

GPG Key: 66AE 2B4A FCCF 3F52 DA18  4D18 4B04 3FCD B944 4540  .''`.
more about me:  https://mapreri.org : :'  :
Launchpad user: https://launchpad.net/~mapreri  `. `'`
Debian QA page: https://qa.debian.org/developer.php?login=mattia  `-


signature.asc
Description: PGP signature

Bug#845715: Required targets must not write outside of the source package tree

2018-11-04 Thread Mattia Rizzolo 
Hi,

On Sat, Nov 03, 2018 at 12:38:55PM -0700, Sean Whitton wrote:
> Given that whole archive rebuilds with use sbuild and already catch
> packages that violate this requirement, making this change would not
> declare any packages buggy that would not already be considered buggy,
> so we can make it right away.

That's not entirely true, I can very easily imagine stuff trying to
write to $HOME but, if failing, trying elsewhere…



Anyway, seconded the below, with or without Russ' amend in
<87woptdiwa@hope.eyrie.org>.
Thank you!

> diff --git a/debian/changelog b/debian/changelog
> index 956f367..b90ea92 100644
> --- a/debian/changelog
> +++ b/debian/changelog
> @@ -10,6 +10,11 @@ debian-policy (4.2.2.0) UNRELEASED; urgency=medium
>  Seconded: Holger Levsen 
>  Seconded: Russ Allbery 
>  Closes: #912581
> +  * Policy: Required targets must not write outside of the source package 
> tree
> +Wording: Johannes Schauer 
> +Seconded: Sean Whitton 
> +Seconded: ...
> +Closes: #845715
>* In a preexisting footnote, recommend passing -D to strip(1) when
>  stripping static libraries.
>  Thanks to Niels Thykier for the suggestion.
> diff --git a/policy/ch-source.rst b/policy/ch-source.rst
> index dc80243..c486e7c 100644
> --- a/policy/ch-source.rst
> +++ b/policy/ch-source.rst
> @@ -291,6 +291,16 @@ For packages in the main archive, no required targets 
> may attempt
>  network access, except, via the loopback interface, to services on the
>  build host that have been started by the build.
> 
> +Required targets must not attempt to write outside of the unpacked
> +source package tree. An exception to this rule is the use of
> +``TMPDIR`` (or ``/tmp`` if that is not set) which is permitted as long
> +as temporary files are deleted by the end of the target, and not
> +reused by subsequent execution of the target.  This restriction is
> +intended to prevent source package builds creating and depending on
> +state outside of themselves, thus affecting multiple independent
> +rebuilds.  In particular, the required targets must not attempt to
> +write into ``HOME``.
> +
>  The targets are as follows:
> 
>  ``build`` (required)
> diff --git a/policy/upgrading-checklist.rst b/policy/upgrading-checklist.rst
> index 899f7e8..70b31bd 100644
> --- a/policy/upgrading-checklist.rst
> +++ b/policy/upgrading-checklist.rst
> @@ -52,6 +52,10 @@ Unreleased.
>  copyright file, but it need not be if creating and maintaining a
>  copy of that information involves significant time and effort
> 
> +4.9
> +Required targets must not write outside of the unpacked source
> +package tree, except for TMPDIR (or /tmp if that is not set).
> +
>  10.1
>  Binaries should be stripped using
>  ``strip --strip-unneeded --remove-section=.comment 
> --remove-section=.note``

-- 
regards,
Mattia Rizzolo

GPG Key: 66AE 2B4A FCCF 3F52 DA18  4D18 4B04 3FCD B944 4540  .''`.
more about me:  https://mapreri.org : :'  :
Launchpad user: https://launchpad.net/~mapreri  `. `'`
Debian QA page: https://qa.debian.org/developer.php?login=mattia  `-


signature.asc
Description: PGP signature