[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Bug#850289: marked as done (debian-policy: Patch so that there is an Example section in manual pages)

Your message dated Sat, 10 Nov 2018 16:56:07 -0700
with message-id <87k1lktrl4.fsf@iris.silentflame.com>
and subject line Re: Bug#850171: Recommend that manpages contain an EXAMPLES section
has caused the Debian Bug report #850171,
regarding debian-policy: Patch so that there is an Example section in manual pages
to be marked as done.

This means that you claim that the problem has been dealt with.
If this is not the case it is now your responsibility to reopen the
Bug report if necessary, and/or fix the problem forthwith.

(NB: If you are a system administrator and have no idea what this
message is talking about, this may indicate a serious mail system
misconfiguration somewhere. Please contact owner@bugs.debian.org
immediately.)


-- 
850171: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=850171
Debian Bug Tracking System
Contact owner@bugs.debian.org with problems
--- Begin Message --- 
Package: debian-policy
Version: 3.9.8.0
Tags: patch
Severity: wishlist

Dear Maintainer,
As shared in #850171 it would be nice if we have Example section in
manpages. This would be especially useful for non-technical users and
a step towards making Debian a truly Universal Operating System.

-- System Information:
Debian Release: stretch/sid
  APT prefers testing
  APT policy: (600, 'testing'), (500, 'unstable-debug'), (500,
'testing-debug'), (1, 'experimental-debug'), (1, 'experimental'), (1,
'unstable')
Architecture: amd64 (x86_64)
Foreign Architectures: i386

Kernel: Linux 4.8.0-2-amd64 (SMP w/2 CPU cores)
Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash
Init: systemd (via /run/systemd/system)

debian-policy depends on no packages.

debian-policy recommends no packages.

Versions of packages debian-policy suggests:
ii  doc-base  0.10.7

-- no debconf information


-- 
          Regards,
          Shirish Agarwal  शिरीष अग्रवाल
  My quotes in this email licensed under CC 3.0
http://creativecommons.org/licenses/by-nc/3.0/
http://flossexperiences.wordpress.com
EB80 462B 08E1 A0DE A73A  2C2F 9F3D C7A4 E1C4 D2D8

From c5848db4f726cbf1b446fd19eaa835f6224a9326 Mon Sep 17 00:00:00 2001
From: Shirish Agarwal <shirishag75@gmail.com>
Date: Thu, 5 Jan 2017 23:37:05 +0530
Subject: [PATCH] debian-policy should ask for/have an Example Section in a manpage, if a manpage exists. 

---
 policy.sgml | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/policy.sgml b/policy.sgml
index 06d094c..a55c4ea 100644
--- a/policy.sgml
+++ b/policy.sgml
@@ -5777,7 +5777,7 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1)
 
 	<p>
 	  Every time the shared library ABI changes in a way that may
-	  break binaries linked against older versions of the shared
+q	  break binaries linked against older versions of the shared
 	  library, the <tt>SONAME</tt> of the library and the
 	  corresponding name for the binary package containing the runtime
 	  shared library should change.  Normally, this means
@@ -10660,6 +10660,13 @@ name ["<var>syshostname</var>"]:
 	  auxiliary things are optional.
 	</p>
 
+        <p> 
+	  It is also suggested that all packages should also have an
+	  EXAMPLE section which describes with syntax how the package
+	  should be used. The Example section could be optional for 
+	  library packages.  
+	  
+	</p>  
 	<p>
           If no manual page is available, this is considered as a bug
           and should be reported to the Debian Bug Tracking System (the
-- 
2.11.0

--- End Message ---
--- Begin Message --- 
tag 850171 +wontfix
thanks

On Sun 04 Nov 2018 at 09:11AM -0800, Russ Allbery wrote:

> Mattia Rizzolo <mattia@debian.org> 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.

Given the lack of consensus, let's just do this instead.  I've edited
that page.

-- 
Sean Whitton

Attachment: signature.asc
Description: PGP signature


--- End Message ---
Reply to: