Bug#934536: info version shipped, but IMO complete, close this bug?

[Osamu Aoki]

Yes, info version is included and it contains appendix, too.

So closing this bug is right action.

Thanks for your effort.


On Thu, 2023-02-09 at 16:28 +, Holger Levsen wrote:
> hi,
> 
> actually I found the info version now, but it seems complete to me:
> 
> $ sudo apt install info
> $ info developers-reference
> 
> # voila. /usr/share/info/developers-reference.info.gz is where the file is.
> 
> So I'm still inclined to close this bug.
> 
> 

Bug#685746: use of Recommends by library

[Osamu Aoki]

Hi,

For recommends, since TC is voted for "We advise the policy maintainers to 
consider
how to clarify ...", here is a reference information for drafting such 
clarification
clause. 

Whereas the original concern of this bug was the use of recommends by 
metapackage,
the underlining issue is broad and unrestricted definition of use of 
recommends, I
think.

>   The Recommends field should list packages that would be found together
>   with this one in all but unusual installations.

The word "together" has no sense of dependency direction.

Related problem is library recommending particular binary as discussed recently 
in
debian-devel:

 Subject: Re: use of Recommends by vlc to force users to use pipewire
 From: Jonas Smedegaard 
 To: debian-de...@lists.debian.org
 Date: Thu, 26 May 2022 17:59:38 +0200 (05/27/2022 12:59:38 AM)
 Message-Id: <165358077835.2132435.4699236542149578...@auryn.jones.dk>

Here Jonas has a interesting view point of "direction".  Let me quote:

> Package relations are directional: Applications need libraries, but
> libraries rarely need applications.
> 
> libpipewire-0.3-0 should not recommend pipewire, because the library
> cannot know if reverse dependencies needs it strongly or weakly.

I know suggest/enhance definition has view point on direction.  I don't see it 
in
recommends.  

In the related posts, issue of recommending xdg-desktop-portal end up pulling in
WebKitGTK is discussed.  This aspect is something to be accounted.

The use of ored recommends in that discussion threads by Vincent is also needs
attention.

> AFAIK, this kind of issue is normally solved with on ORed Recommends
> (when a virtual package is not defined for that). For instance,
> libaspell15 has
> 
>   Recommends: aspell-en | aspell-dictionary | aspell6a-dictionary
> 
> So, if the user already chose a solution, it won't be overridden
> by the default.
> 
> Here, this could be
> 
>   Recommends: pipewire | pulseaudio
> 
> but IMHO, it is not up to libraries to do such Recommends, but
> to audio applications or desktop environments, or something
> done automatically at installation time where the user chooses
> which kind of installation he wants? But isn't a sound system
> already installed by default with a typical installation of a
> desktop machine?

I think another direction question is data package to utility tool, and 
documentation
package to its utility.

Also considering normal use cases, circular dependency created by 
depends+recommends
combination needs to be addressed to avoid situation like:
  https://bugs.debian.org/655483

Technical solution by aptitude is one thing but having sane policy to avoid 
creating
such cases as much as possible is desirable thing.  Having some thing of 
"direction"
in recommends usage definition may help.

Just a thought.

Regards,

Osamu

PS: BCCed people quoted.

Bug#934536: sphinx-info

[Osamu Aoki]

Hi,

Actually, text after .toctree are included at the end of entire info
page.  

For now, not using text after .toctree is a reasonable work around.

But the best solution is to write extension to emmit such text after
.toctree immediately after @menu section in *.texi file.

So let's make this bug report tracking this extension while implementing
workaround for https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=934526

Osamu

Bug#934536: info page needs to include more from index.rst

[Osamu Aoki]

Source: developers-reference
Version: 11.0.1
Severity: minor


For info page building, text before toctree is included in the opening
info page but after is silently dropped.

Also it doesn't care appendix.

I am trying to include copyright text into the first opening page.

-- System Information:
Debian Release: 10.0
  APT prefers stable
  APT policy: (500, 'stable')
Architecture: amd64 (x86_64)

Kernel: Linux 4.19.0-5-amd64 (SMP w/4 CPU cores)
Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8), 
LANGUAGE=en_US.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash
Init: systemd (via /run/systemd/system)
LSM: AppArmor: enabled

-- no debconf information

Bug#934529: New incoming system

[Osamu Aoki]

Source: developers-reference
Version: 3.4.26, 11.0.1
Severity: wishlist

IRC on describing new incoming system:
  Robot101: do you have a URL describing new incoming system?
  
https://lists.debian.org/debian-devel-announce/2002/debian-devel-announce-200202/msg6.html

Hi,

Below are details of the proposed new incoming system.  This should
have been done a long time ago but in any event the ongoing move
towards crypto-in-main pushed it forward.  The code is 99% (re)written
and being tested locally.  As with the original pools implementation,
the plan is to implement it on non-US first and then ftp-master when
non-US is settled and working.

 NOTE **

!! DO NOT UPLOAD CRYPTO TO FTP-MASTER !!

This does NOT mean you can upload crypto yet.  This is just one step
in the crypto-in-main transition.  When the requisite legal hoops have
been jumped through, there will be an announcement but until then
current practice (and policy) applies, i.e. no crypto or crypto
dependents in main.

!! DO NOT UPLOAD CRYPTO TO FTP-MASTER !!

 NOTE **

- 
---

 Proposed New Incoming System
 

This document outlines the proposed new system for handling the
Incoming directories on ftp-master and non-US.

The present:
- 

  o incoming is a world writable directory

  o incoming is available to all through http://incoming.debian.org/

  o incoming is processed once a day by dinstall

  o uploads in incoming must have been there > 24 hours before they
are REJECTed.  If they are processed before that and have problems
they will be SKIPped (with no notification to the maintainer and/or
uploader).

The proposed future:
- 

  o There will be 4 incoming directories:

 @ "unchecked"  - where uploads from Queue Daemons and maintainers
  initially go

 @ "install"- where installable packages stay until the daily
  dinstall run

 @ "new"- where NEW packages (and their dependents[1]) requiring
  human processing go after being automatically
  checked by dinstall.

 @ "byhand" - where BYHAND packages (and their dependents[1])
  requiring human intervention go after being
  automatically checked by dinstall.

In addition there will be 3 support directories:

 @ "reject" - where rejected uploads go

 @ "done"   - where the .changes files for packages that have been
  installed go.

 @ "holding"- a temporary working area for dinstall to hold
  packages while checking them.

  o Packages in 'unchecked' are automatically checked every 15 minutes
and are either: REJECT, ACCEPT (i.e. -> 'install'), NEW or BYHAND.

  o Only 'unchecked' is locally world-writeable.  The others are all,
of course, locally world-readable but only 'install' and 'byhand'
are publicly visible on http://incoming.debian.org/

  o 'install' and 'byhand' are made available to the auto-builders so
 they can build out of them.

  o 'install' is processed once a day as before.

  o list notification and bug closures are changed to be done for
ACCEPTs, not INSTALLs. Mail is sent only to the maintainer/uploader
on INSTALL.
[Rationale: this reduces the load both on our list server and our
 BTS server; it also gives people better notice of uploads to
 avoid duplication of work especially, for example, in the case of NMUs]
[NB: see [3] for clarifications of when ACCEPT/INSTALL mails are sent]

Why:
- 

  o Security (no more replaceable file races)
  o Integrity (new http://i.d.o contains only signed (+installable) uploads[2])
  o Needed for crypto-in-main integration
  o Allows safe auto-building out of incoming
  o Allows previously-prohibitively-expensive checks to be added to dinstall
  o Much faster feedback on packages; no more 48 hour waits before
finding out your package has been REJECTed.

What breaks:
- 

  o uploads of large packages directly to incoming over a slow link
can lead to bogus rejections.

* solution: Ensure the .changes file is the last file to be
uploaded (dput and dupload already do this) or upload
to a temporary directory then mv them into place with
ssh.

  o people who upload packages but then want to retract or replace the
upload.

* solution: mostly "Don't do that then"; i.e. test your uploads
  properly.  Uploads can still be replaced, simply by uploading a
  higher versioned replacement.  Total retraction is harder but
  usually only relevant for NEW packages.



[1] For versions of dependents meaning: 

Bug#934528: email gate and db/LDAP

[Osamu Aoki]

Source: developers-reference
Version: 3.4.26, 11.0.1
Severity: wishlist

Please mention email gate

 https://lists.debian.org/debian-devel/1999/12/msg00627.html

by From: Jason Gunthorpe 

On Fri, 10 Dec 1999, Juan Cespedes wrote:

> I connect directly to db.debian.org, and I _think_ I get that message
> directly from db.debian.org.

Strange Strange

> BTW, is there any way to change the settings in the developper
> database without using the WWW server at db.debian.org?  I remember
> there was a `cha...@db.debian.org', but I don't know how does it work.

There is of course the mailgateway.. If you run man ud-mailgate on a box
you can get the information on how to use it..

Jason

TITLE INFORMATION: ud-mailgate(1)
AUTHOR INFORMATION: userdir-ldap
DATE INFORMATION: 28 Sep 1999

NAME
ud-mailgate - PGP mail gateway to the LDAP directory

SYNOPSIS

  ud-mailgate function

DESCRIPTION

ud-mailgate implements a PGP secured mail gateway to an LDAP directory that
allows users to safely and conviently effect changes to their entries. It
makes use of PGP signed input messages to positivly identify the user and
to confirm the validity of the request. Furthermore it implements a replay
cache that prevents the gateway from accepting the same message more than
once.

There are three functions logically split into 3 sperate email addresses
that are implemented by the gateway: ping, new password and
changes. The function to act on is the first argument to the program.

ud-mailgate was designed to take its message on stdin from a mailsystem like
Exim, with full message headers intact. It transparently decodes PGP/MIME
and PGP clearsigned messages and passes them through GnuPG for verification.
Support for PGP2.x users is maintained by passing options to GunPG that
generate encrypted messages they are able to decode, however this option
is only enabled for PGP2.x keys, OpenPGP keys use the new packet formats.

Error handling is currently done by generating a bounce message and passing
descriptive error text to the mailer. For mailers like Exim this generates a
very hard to read message, but it does have the relevent information
embedded in it.

PING

The ping command simply returns the users public record. It is usefull for
testing the gateway and for the requester to get a basic dump of their
record. In future this address might 'freshen' the record to indicate the
user is alive. Any PGP signed message will produce a reply.

NEW PASSWORD

If a user looses their password they can request that a new one be generated
for them. This is done by sending the phrase "Please change my Debian
password" to chpas...@db.debian.org. The phrase is required to prevent the
daemon from triggering on arbitary signed email. The best way to invoke this
feature is with echo "Please change my Debian password" | gpg
--clearsign | mail chpas...@db.debian.org
After validating the request the daemon will generate a new random password,
set it in the directory and respond with an ecrpyted message containing the
new password. The password can be changed using one of the other interface
methods.

CHANGES

An address is provided for making almost arbitary changes to the contents of
the record. The daemon parse its input line by line and acts on each line in
a command oriented manner. Anything, except for passwords, can be changed
using this mechanism. Note however that because this is a mail gateway it
does stringent checking on its input. The other tools allow fields to be set
to virtually anything, the gateway requires specific field formats to be met.

o Arbitary Change
A line of the form 'field: value' will change the contents of the field
to value. Some simple checks are performed on value to make sure that it is
not sent to nonsense. The values that can be changed are: c, l,
facsimiletelephonenumber, telephonenumber, postaladdress, postalcode,
loginshell, emailforward, ircnick, onvacation, and onvacation. See
ud-info(1) for information on the meanings of each field type.

o Latitude/Longitude Change
The daemon has a special parser to help changing latitude and longitude
values. It accepts several common formats for position information and
converts them to one of the standard forms. The permitted types are
D = Degrees, M = Minutes, S = Seconds, x = n,s,e,w
+-DDD.D, +- DDDMM., +-DDDMMSS. [standard forms]
DDxMM., DD:MM. x, DD:MM:SS.SSS X
and the request format is 'Lat: xxx Long: xxx' where xxx is one of the
permitted types. The resulting response will include how the input was
parsed and the value in decimal degrees.

o SSH RSA Authentication key load
Part of the replicated dataset is a virtual .ssh/authorized_keys file for
each user. The change address is the simplest way to set the RSA key(s) you
intend to use. Simply place a key on a line by itself, the full SSH key
format specification is supported, see sshd(8). Probably the most common way
to use this function will be cat .ssh/identity.pub | gpg --clearsign |
mail 

Bug#934527: Sphinx conversion needs to take care appendix etc.

[Osamu Aoki]

Source: developers-reference
Version: 3.4.26, 11.0.1
Severity: minor

Index for appendix used to be A.1, A.1.1, ... but now A is missing.
(This may be more issue with singlehtml )
This needs to be addressed some day.

Also, debian/tocsubstvars needs to be updated to match this.

I also think it is better to drop "*" but keep chapter index.

 CURRENT PACKAGE DESCRIPTION ---
Table of Contents:

   * 1. Scope of This Document
   * 2. Applying to Become a Member
   * 3. Debian Developer's Duties
   * 4. Resources for Debian Members
   * 5. Managing Packages
   * 6. Best Packaging Practices
   * 7. Beyond Packaging
   * 8. Internationalization and Translations
   * 1. Overview of Debian Maintainer Tools


 DESIRABLE ---
Table of Contents:

   1. Scope of This Document
   2. Applying to Become a Member
   3. Debian Developer's Duties
   4. Resources for Debian Members
   5. Managing Packages
   6. Best Packaging Practices
   7. Beyond Packaging
   8. Internationalization and Translations
   A. Overview of Debian Maintainer Tools

-- System Information:
Debian Release: 10.0
  APT prefers stable
  APT policy: (500, 'stable')
Architecture: amd64 (x86_64)

Kernel: Linux 4.19.0-5-amd64 (SMP w/4 CPU cores)
Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8), 
LANGUAGE=en_US.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash
Init: systemd (via /run/systemd/system)
LSM: AppArmor: enabled

-- no debconf information

Bug#934526: Initial page lacks contents after sphinx conversion

[Osamu Aoki]

Source: developers-reference
Version: 3.4.26, 11.0.1
Severity: minor

## ISSUE ##

Following contents are missing:

Developer's Reference Team

Andreas Barth
Adam Di Carlo
Raphaël Hertzog
Lucas Nussbaum
Christian Schwarz
Ian Jackson
ver. 3.4.25

Copyright © 2004, 2005, 2006, 2007 Andreas Barth

Copyright © 1998, 1999, 2000, 2001, 2002, 2003 Adam Di Carlo

Copyright © 2002, 2003, 2008, 2009 Raphaël Hertzog

Copyright © 2008, 2009 Lucas Nussbaum

Copyright © 1997, 1998 Christian Schwarz

This manual is free software; you may redistribute it and/or modify it under 
the terms of the GNU General Public License as published by the Free Software 
Foundation; either version 2, or (at your option) any later version.

This is distributed in the hope that it will be useful, but without any 
warranty; without even the implied warranty of merchantability or fitness for a 
particular purpose. See the GNU General Public License for more details.

A copy of the GNU General Public License is available as 
/usr/share/common-licenses/GPL-2 in the Debian distribution or on the World 
Wide Web at the GNU web site. You can also obtain it by writing to the Free 
Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 
02110-1301, USA.

If you want to print this reference, you should use the pdf version. This 
manual is also available in some other languages.

2019-06-15

## RESOLUTION ##

Update index.rst manually.




-- System Information:
Debian Release: 10.0
  APT prefers stable
  APT policy: (500, 'stable')
Architecture: amd64 (x86_64)

Kernel: Linux 4.19.0-5-amd64 (SMP w/4 CPU cores)
Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8), 
LANGUAGE=en_US.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash
Init: systemd (via /run/systemd/system)
LSM: AppArmor: enabled

-- no debconf information

Bug#934525: French addendum is missing after Sphinx conversion

[Osamu Aoki]

Source: developers-reference
Version: 11.0.1
Severity: minor

## ISSUE ##

Sphinx conversion dropped content oof 3.4.25 po4a/add_fr/scope.add


PO4A-HEADER:mode=after;position=De plus ce document;endboundary=


Avertissement

Bien que ce document soit en français, l'activité de responsable Debian
implique une maîtrise de la langue anglaise. Le projet Debian est un
projet international auquel participent des japonais, néo-zélandais,
américains, allemands, finlandais, français, espagnols, danois, etc.


En conséquence, la langue utilisée dans toutes les listes de diffusion
destinées aux développeurs (à l'exception de la liste
debian-devel-french@) est l'anglais et les
rapports de bogue doivent être rédigés en anglais. En fait, sauf
exception rare, tout dialogue avec les autres responsables Debian se
fera en anglais quel que soit le média.



---
(Translation to English)

 Warning 

Although this document is in French, the Debian Manager activity
involves a command of the English language. The Debian project is an
international project involving Japanese, New Zealanders, Americans,
Germans, Finnish, French, Spanish, Danish, etc.


As a result, the language used in all mailing lists intended developers
(except for the list  debian-devel-french @ & lists-host;  is English and reports bug must be written in English. In fact,
with rare exceptions, everything dialogue with other Debian officials
will be in English regardless of the media.

## RESOLUTION ##

Option 1:
Add equivalent in English and offer translation.

Option 2:
Add extension to sphinx build process to add equivalent translation addendum 
feature.

-- System Information:
Debian Release: 10.0
  APT prefers stable
  APT policy: (500, 'stable')
Architecture: amd64 (x86_64)

Kernel: Linux 4.19.0-5-amd64 (SMP w/4 CPU cores)
Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8), 
LANGUAGE=en_US.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash
Init: systemd (via /run/systemd/system)
LSM: AppArmor: enabled

-- no debconf information

Bug#931548: Migration to Sphinx -- developers-reference

[Osamu Aoki]

Hi,

On Sun, Aug 11, 2019 at 03:25:59PM +, Holger Levsen wrote:
> On Sun, Aug 11, 2019 at 11:51:32PM +0900, Osamu Aoki wrote:
> > I saw you uploaded a new version.  Thanks.
> 
> most changes were from you, so thank you very much too!
> 
> > As I see this package, remaining tasks are:
> 
> this list looks good to me. highest prio for me is getting
> https://www.debian.org/doc/devel-manuals#devref fixed though.

OK.  I will work on this next.  That is cron script.

But before doing it, I will record issues to BTS.

Osamu

Bug#931548: Migration to Sphinx -- developers-reference

[Osamu Aoki]

Hi,

On Sat, Aug 10, 2019 at 04:35:26PM +, Holger Levsen wrote:

I saw you uploaded a new version.  Thanks.

As I see this package, remaining tasks are:

Priority Issues
* A  Fix reproducible builds: date calculation with (TZ?) (shell)
*  B Fix reproducible builds: different_due_to_umask (shell)
*   CFix reproducible builds: epub/zip timestamp (?shell)
*   CAdd link to txt.gz, epub (template/javascript)
*D   Adjust color and cosmetics of web page (css)
*  B Fix singlehtml builds with correct footnote etc. (python extension)
*  B Fix singlehtml builds with correct section indexing. (python extension)
*   CFix html/... for appendix indexing. (python extension)
*   CFrench addendum (implement addendum python extension)
 (Adding English placeholder text is another approach)
*  B Cover page
*   CPackage description in d/control has very slightly changed TOC lines

I am playing with the pudb python debugger to learn how docutils/sphinx works 
:-)

Osamu

Bug#931548: Migration to Sphinx -- developers-reference

[Osamu Aoki]

Hi,

With today's commit, pull-down language selection seems to work for
package installed files.  Also now we have Gnome desktop icon ;-)

It is usable, I think.

> > If I figure how to set up option2 type i18n web page, I may even do it
> > for debian-handbook.
> 
> yeah, I also strongly prefer option 2.

I think I figured out OK.  This is my first web page using javascript.

It should be easy to add menu to select pdf/text/epub download now just by
updating the existing template file and javascript.

If any of you have good sense of color, adjusting color via CSS may be
an option for this pull-down menu.

Your feed back is most appreciated.

Osamu

Bug#931548: Migration to Sphinx

[Osamu Aoki]

HI,

On Sun, Jul 28, 2019 at 06:39:07PM +0100, Sean Whitton wrote:
> Hello,
> 
> On Sat 27 Jul 2019 at 06:31pm +09, Osamu Aoki wrote:
> 
> > Yes.  Eventually ;-)
> >
> > I also see the translation of Policy is building only HTML.
> 
> We can add others upon request.

OK.

> > I think I am going to rewrite build script more symmetrically to make it
> > easy to build all formats for all languages.
> >
> > Just give me some time with developers-reference get this sorted out.
> 
> Okay -- Policy's build is already quite complex so please try to keep
> the patch as small as possible.

Yes I know.  Let me make simple clean multi-language build script while
using -b option with sphinx-build.  -M option is buggy if I try to use
-d or move build directory in subdirectory for developers-reference.

Before going for debian-policy, I still need to get javascripts symlink as
.link.  Then I also need to come up with pull down language
selector.

Also addendum is not supported now.

Once I get them all right, I will copy it into policy in which many
non-sphinx docs are build too.  I don't think current Japanese HTML
build location is the best place.

Osamu

Bug#931548: Migration to Sphinx

[Osamu Aoki]

Hi,

On Fri, Jul 26, 2019 at 09:47:57PM +0100, Sean Whitton wrote:
> Hello,
> 
> On Fri 26 Jul 2019 at 08:19PM +00, Holger Levsen wrote:
> 
> >> I mean that the English files are available on
> >> www.debian.org but translations don't show up as described in
> >> https://www.debian.org/intro/cn This is because  all html files are
> >> names as index.html etc. without language code, so automatic language
> >> selection can not be implemented.
> >>
> >> We can do 2 ways.
> > [...]
> >> If I figure how to set up option2 type i18n web page, I may even do it
> >> for debian-handbook.
> >
> > yeah, I also strongly prefer option 2.
> 
> Would this also be useful to get the translations of debian-policy
> published on the mirrors too?

Yes.  Eventually ;-)

I also see the translation of Policy is building only HTML.

I think I am going to rewrite build script more symmetrically to make it
easy to build all formats for all languages.

Just give me some time with developers-reference get this sorted out.

Osamu

Bug#931548: Migration to Sphinx

[Osamu Aoki]

Hi,

On Wed, Jul 24, 2019 at 08:40:19PM +, Holger Levsen wrote:
> hi,
> 
> dear debian-www people: src:developers-reference was just switched to
> use sphinx, just like src:debian-policy. However, no upload to unstable
> has been made yet...
> 
> On Tue, Jul 23, 2019 at 08:13:50AM -0700, Sean Whitton wrote:
> > On Mon 22 Jul 2019 at 09:22pm +00, Holger Levsen wrote:
> > > I wonder how this was done for debian-policy which is also hosted on
> > > www.debian.org. Sean, do you have any insight on this?
> > Paul, Laura and Osamu hacked on the www-team's scripts until it worked
> > -- I'm afraid I wasn't involved other than reporting problems with the
> > published version of Policy, and I don't think we made changes to our
> > package in response to any requests from the www-team.
> 
> Am I correct to assume we could go a similar way with 
> src:developers-reference ?

Yes.

Only remaining problem is it builds multi-language outputs as packages
but not for web.  I mean that the English files are available on
www.debian.org but translations don't show up as described in
https://www.debian.org/intro/cn This is because  all html files are
names as index.html etc. without language code, so automatic language
selection can not be implemented.

We can do 2 ways.  

Option 1: 
~
This approach was deployed for "The Debian Administrator's Handbook" 
https://www.debian.org/doc/user-manuals#debian-handbook

I wrote a sed script to change internal reference URLs while adding
language code to html filename extensions.  This script is run by cron
script when binary packages are unpacked and unpacked files are
installed.

I know it works but i18n via https://www.debian.org/intro/cn is not as
friendly as menu-driven selection as below.

Option 2:
~
I am looking for i18n web page like:
 https://docs.python.org/3/
 https://docs.python.org/3/library/index.html
 https://docs.python.org/3/reference/index.html
where language can be selected via pull down menu.

These seem to be built via sphinx-doc.  So this native sphinx i18n
approach seems to be better option than option 1 which use intrusive and
fragile sed script.

If I figure how to set up option2 type i18n web page, I may even do it
for debian-handbook.

> If you wanted, you could test by cloning the git repo, install the
> build-depends and run 'make'. The package build is still broken...

Yah... that part is easy.

Osamu

Bug#931548: Migration to Sphinx

[Osamu Aoki]

Hi,

On Mon, Jul 22, 2019 at 09:22:07PM +, Holger Levsen wrote:
> I wonder how this was done for debian-policy which is also hosted on
> www.debian.org. Sean, do you have any insight on this?

Alas, I thought I checked.  Somehow I thought policy doesn't have
translation.  Wrong!!!  (I already had its git checkout here.)

Although it is a bit complicated Makefile, this gives me a good start.

This lacks language selection support, though.  Also, www.debian.org
only publishes English page now.  That's something to be improved.

Thanks for reminder.

Osamu 

PS: I am busy.  If anyone update the branch, I am happy.  Otherwise, I
will come back to fix it.

Bug#931548: Migration to Sphinx

[Osamu Aoki]

Hi,

On Mon, Jul 22, 2019 at 01:45:50AM +, Holger Levsen wrote:
...
> > Maybe, now I think Sphinx expert can take over to get proper packaging.
> 
> yeah, indeed! ;)

Do you know anyone good in this.   Is there any volunteer?  (I am
seeking help on the mailinglist at sphinx-us...@googlegroups.com now)

> I think it's ok if the master branch is broken for some time, this
> conversation has been much desired to get developers-reference in an
> editable state again, so here we go.

One thing stopping me to move forward is the difference of i18n HTML
page arrangement:

 * Debian web site https://www.debian.org/doc/manuals/developers-reference/
   It offers the automatic locale adjusted content by using
   index.en.html, index.fr.html, ...
 * Sphinx based web sites such as https://docs.python.org/3/
   It offers the manual pull-down menu and web pages are placed at
   .../en/index.html .../fr/index.html

How should we arrange web page? I want to migrate to Sphinx-style.
But that will break current URL links.  Any opinion?

Please note Debian web pages will be generated from the latest unstable
version binary package.  (Yes, "sed" scripts in cron work if written
correctly but that seems very fragile.)

Regards,

Osamu

Bug#931548: Migration to Sphinx

[Osamu Aoki]

Package: src:developers-reference
Version: 3.4.25
Severity: wishlist
Tags: patch

Patch is provided as rest8 branch.
  https://salsa.debian.org/debian/developers-reference/tree/rest8


├── debian
│   ├── changelog
│   ├── control
│   ├── copyright
│   ├── developers-reference-de.doc-base
│   ├── developers-reference-de.docs
│   ├── developers-reference.doc-base
│   ├── developers-reference.docs
│   ├── developers-reference-fr.doc-base
│   ├── developers-reference-fr.docs
│   ├── developers-reference-it.doc-base
│   ├── developers-reference-it.docs
│   ├── developers-reference-ja.doc-base
│   ├── developers-reference-ja.docs
│   ├── developers-reference-ru.doc-base
│   ├── developers-reference-ru.docs
│   ├── rules
│   ├── source
│   │   └── format
│   ├── tocsubstvars
│   └── TODO
├── Makefile
├── README.contributing
├── source
│   ├── best-pkging-practices.rst
│   ├── beyond-pkging.rst
│   ├── conf.py
│   ├── developer-duties.rst
│   ├── index.rst
│   ├── l10n.rst
│   ├── locales
│   │   ├── de
│   │   │   └── LC_MESSAGES
│   │   │   ├── best-pkging-practices.po
│   │   │   ├── beyond-pkging.po
│   │   │   ├── developer-duties.po
│   │   │   ├── index.po
│   │   │   ├── l10n.po
│   │   │   ├── new-maintainer.po
│   │   │   ├── pkgs.po
│   │   │   ├── resources.po
│   │   │   ├── scope.po
│   │   │   └── tools.po
│   │   ├── fr
│   │   │   └── LC_MESSAGES
│   │   │   ├── best-pkging-practices.po
│   │   │   ├── beyond-pkging.po
│   │   │   ├── developer-duties.po
│   │   │   ├── index.po
│   │   │   ├── l10n.po
│   │   │   ├── new-maintainer.po
│   │   │   ├── pkgs.po
│   │   │   ├── resources.po
│   │   │   ├── scope.po
│   │   │   └── tools.po
│   │   ├── it
│   │   │   └── LC_MESSAGES
│   │   │   ├── best-pkging-practices.po
│   │   │   ├── beyond-pkging.po
│   │   │   ├── developer-duties.po
│   │   │   ├── index.po
│   │   │   ├── l10n.po
│   │   │   ├── new-maintainer.po
│   │   │   ├── pkgs.po
│   │   │   ├── resources.po
│   │   │   ├── scope.po
│   │   │   └── tools.po
│   │   ├── ja
│   │   │   └── LC_MESSAGES
│   │   │   ├── best-pkging-practices.po
│   │   │   ├── beyond-pkging.po
│   │   │   ├── developer-duties.po
│   │   │   ├── index.po
│   │   │   ├── l10n.po
│   │   │   ├── new-maintainer.po
│   │   │   ├── pkgs.po
│   │   │   ├── resources.po
│   │   │   ├── scope.po
│   │   │   └── tools.po
│   │   └── ru
│   │   └── LC_MESSAGES
│   │   ├── best-pkging-practices.po
│   │   ├── beyond-pkging.po
│   │   ├── developer-duties.po
│   │   ├── index.po
│   │   ├── l10n.po
│   │   ├── new-maintainer.po
│   │   ├── pkgs.po
│   │   ├── resources.po
│   │   ├── scope.po
│   │   └── tools.po
│   ├── new-maintainer.rst
│   ├── pkgs.rst
│   ├── resources.rst
│   ├── scope.rst
│   ├── _static
│   └── tools.rst
└── sphinx-multi

You can build HTML and PDF with "make".

debian/* still needs to be polished as of this posting.

The conversion process is completely recorded in the history.  If main branch
is update, we can rebase most of rest8 and do the operation as in the commit
message to get conversion for the updated master if needed.

Maybe, now I think Sphinx expert can take over to get proper packaging.

Osamu

-- System Information:
Debian Release: 10.0
  APT prefers stable
  APT policy: (500, 'stable')
Architecture: amd64 (x86_64)

Kernel: Linux 4.19.0-5-amd64 (SMP w/4 CPU cores)
Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8), 
LANGUAGE=en_US.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash
Init: systemd (via /run/systemd/system)
LSM: AppArmor: enabled

Re: Converting dev-ref to use rST

[Osamu Aoki]

Hi,

On Mon, Jun 24, 2019 at 02:04:43AM +0900, Osamu Aoki wrote:
> Hi,
> 
> On Tue, Jun 18, 2019 at 12:15:52AM +0900, Osamu Aoki wrote:
> > Hi,
> > 
> > I found one Italian translation error.  (bogus duplicate copy of msgstr)
> > 
> > On Sun, Jun 16, 2019 at 10:03:35PM +0900, Osamu Aoki wrote:
> > > Hi,
> > > 
> > > I realize I can do better ...
> > 
> > Instead of sed, I am replacing text with a short python script to deal
> > with markup across lines.
> 
> I found Russian irregularities and pandoc fussiness on docbook
> whitespaces etc.
> 
> I think conversion is OK with rest8 branch.  I just need to figure out
> how to build Sphinx with PO.

Well ... many problems were found.  Some in original translation PO source.

I think I did OK for sphinx, I need to update this for packaging.

 https://salsa.debian.org/debian/developers-reference/tree/rest8

Problem is Sphinx uses different strategy to provide multiple languages
from one used on www.debian.org.  I guess following Python site
convention seems good idea.

I will keep working on this branch.

Osamu

Re: Converting dev-ref to use rST

[Osamu Aoki]

Hi,

On Tue, Jun 18, 2019 at 12:15:52AM +0900, Osamu Aoki wrote:
> Hi,
> 
> I found one Italian translation error.  (bogus duplicate copy of msgstr)
> 
> On Sun, Jun 16, 2019 at 10:03:35PM +0900, Osamu Aoki wrote:
> > Hi,
> > 
> > I realize I can do better ...
> 
> Instead of sed, I am replacing text with a short python script to deal
> with markup across lines.

I found Russian irregularities and pandoc fussiness on docbook
whitespaces etc.

I think conversion is OK with rest8 branch.  I just need to figure out
how to build Sphinx with PO.

Osamu

Re: Converting dev-ref to use rST

[Osamu Aoki]

Hi,

I found one Italian translation error.  (bogus duplicate copy of msgstr)

On Sun, Jun 16, 2019 at 10:03:35PM +0900, Osamu Aoki wrote:
> Hi,
> 
> I realize I can do better ...

Instead of sed, I am replacing text with a short python script to deal
with markup across lines.

Please wait...

Osamu

Re: Converting dev-ref to use rST

[Osamu Aoki]

Hi,

I realize I can do better ...

Redoing the whole thing again...

Osamu

Bug#930553: how about encoding ???

[Osamu Aoki]

Hi,
On Sat, Jun 15, 2019 at 03:53:07PM +, Holger Levsen wrote:
> On Sat, Jun 15, 2019 at 09:04:24PM +0900, Osamu Aoki wrote:
> > While doing sphinx conversion, I realized that it may be better to
> > update as follows:
...

If you see my initial diff on the first line of common.ent

 -
 +

Although for ASCII code range (7-bits), iso-8859-1, utf-8, ascii are the
same, shouldn't we use UTF-8 in line with XML code?  Was there any
specific issues to do this?

THis is no rush but I think this is the right way (Am I wrong?)

Regards,

Osamu

Re: Converting dev-ref to use rST

[Osamu Aoki]

Hi,

"rest3" started and removed old ones.
 
> > > 3.  inter-chapter reference to section title lacks section title text 
> > > auto-filling
> > > For example  `??? <#key-maint>`__ 
> 
> This was easy.  :ref:`...`
> I just have to automate it to address all incidents.

There were another type of pandoc problem.  So I made another sed
script.

I have completed to make sphinx transition under sphinx/ directory.

I guess, next action should be one by a sphinx expert to set up proper
multi-language build tree system.  Right now, only one translation at a
time.

I hope this is good enough for me to leave this to you.
PO conversion is done in "rest3" branch.  All history is documented
there, if you find bug and do it again.

I think author name, copyright, ... etc. can be done by sphinx experts.

My work to convert PO is done.

What do you think?

Osamu

Bug#930553: version-nexttesting should be "11" (not "10")

[Osamu Aoki]

Package: src:developers-reference
Version: 3.4.24
Severity: normal

While doing sphinx conversion, I realized that it may be better to
update as follows:


$ git diff
diff --git a/common.ent b/common.ent
index 83eddf3..900ce90 100644
--- a/common.ent
+++ b/common.ent
@@ -1,4 +1,4 @@
-
+
 
 

Re: Converting dev-ref to use rST

[Osamu Aoki]

Hi,

"rest2" started.

> > 3.  inter-chapter reference to section title lacks section title text 
> > auto-filling
> > For example  `??? <#key-maint>`__ 

This was easy.  :ref:`...`
I just have to automate it to address all incidents.

I still need to figure out to use substitute 

Also, I need to figure out how to add author names etc...

Osamu

Re: Converting dev-ref to use rST

[Osamu Aoki]

Hi,

"rest1" started.

> 1.   need to replace @@@...@@@  by |...|
done

> and figure out to use substitute
TODO

> 2.  pandoc without "--reference-links" seems better
> As far as HTML result, works fine except missing toctree
> This should be addressed manually

toctree added manually: done

> 3.  inter-chapter reference to section title lacks section title text 
> auto-filling
> For example  `??? <#key-maint>`__ 
TODO


Looks like it works OK.

I need to figure out to use substitute and inter-file reference.  

Osamu

Re: Converting dev-ref to use rST

[Osamu Aoki]

Hi,

I tried further with experimental rest branch.

I think I need to redo the whole thing again to get cleaner result but
this is good learning.

Now I have narrowed down issues as follows:

1.   need to replace @@@...@@@  by |...| and figure out to use substitute
or embed all entity references (DBK)

2.  pandoc without "--reference-links" seems better
As far as HTML result, works fine except missing toctree
This should be addressed manually
 
3.  inter-chapter reference to section title lacks section title text 
auto-filling
For example  `??? <#key-maint>`__ 

2 is trivial

1 and 3 are non-trivial which requires me to get used to Sphinx a bit
more.

I may start new branch "rest1".

Osamu

Re: Converting dev-ref to use rST

[Osamu Aoki]

Hi,

I pushed the "rest" branch.  

> NOW
> 
> to SED script
> 
> s/@@@codename-oldoldstable@@@/wheezy/g

By the way, is there better approach?  I am new to reST build.
I am holding off here.

Now "make" will get you a set of localized reST files.  Please inspect
this result.

I don't know how good pandoc worked.

Good night.

Osamu

Re: Converting dev-ref to use rST

[Osamu Aoki]

Hi,

On Wed, Jun 12, 2019 at 10:08:40PM +0900, Osamu Aoki wrote:

...

> This is one way reST to POT and POT to PO merge and translated reST
> generation tool (Unlike po4a, we can't make po from matching translation
> reST source.)
>http://www.sphinx-doc.org/en/stable/intl.html
> 
> So my script comes handy to do this po generation from matching translation
> reST source.
>https://github.com/osamuaoki/poutils

Anyway, let me start rest branch. (At least locally).

Oops.  How does reST infrastructure handle entity definition equivalent.

Currently, DATA type content is defined in common.ent to avoid noise to
translator.

One way is to change these 

NOW


to SED script

s/@@@codename-oldoldstable@@@/wheezy/g

to deal this.  To do this we need to preload common.ent with a dummy
data.  Then we should get nice base XML without entity reference.

A template English reST >+- SED --- Good English reST
 |
PO file (template based)>+- SED --- Good Translation reST

We need to escape few characters such as / and ~ and @ if needed.

Maybe we need to touch up   tags ... automating it may
be more trouble so let's skip.

Osamu

Re: Converting dev-ref to use rST

[Osamu Aoki]

On Tue, Jun 11, 2019 at 05:29:16PM +, Holger Levsen wrote:
> On Tue, Jun 11, 2019 at 10:15:56AM -0700, Sean Whitton wrote:
> > I don't know of any automated solution.  We might just have to keep the
> > old source and continue building translations from that until each
> > language is manually converted?  :\
> 
> once we have a script which does the conversion, cant we use po4a to
> generate a $language version as docbook, then run the converting script
> on it and then recreate the po file from the new format?

Current best practice to internationalize reST is to use
   SPHINXINTL = sphinx-intl
(This is used by policy now)

This is one way reST to POT and POT to PO merge and translated reST
generation tool (Unlike po4a, we can't make po from matching translation
reST source.)
   http://www.sphinx-doc.org/en/stable/intl.html

So my script comes handy to do this po generation from matching translation
reST source.
   https://github.com/osamuaoki/poutils

Osamu

Re: Converting dev-ref to use rST

[Osamu Aoki]

Hi,

On Mon, Apr 08, 2019 at 02:45:29PM -0700, Sean Whitton wrote:
> Hello,
> 
> I am considering to working to convert dev-ref to rST+Sphinx this
> summer.  I would like to start a discussion about doing that.  The
> main things that I need to learn from this discussion are:
> 
> - who else is interested in working on this;
> 
> - whether I should use the scripts that were used to convert
>   debian-policy Debian-SGML->docbook->rST+Sphinx, or instead write a
>   new Debian-SGML->rST+Sphinx converter; and

I recommend to do:

 Debian-SGML->docbook xml (This is must.  This is one line command)

 optional
 docbook xml -> xml with any tweak if needed
with simple xmlt tricks
(Of course, pandoc converter may be tweaked too)
   xml -> rST+Sphinx with pandoc -- my choice
  --- Q: How good is this?

   xml -> rST+Sphinx with custom xslt scripts 
  -- if someone care to do...?

Also, we need to pick PO system for rST+Sphinx?
Can anyone point me to it.

 * If it is po4a, making PO from matched rST+Sphinx
   is no-brainer.
 * If it is any other script framework, we can still do it
   easily.  (via mo file etc.)
   I have done some work along this line so we can use that
   scripts.  https://github.com/osamuaoki/poutils

> - whether there is some reason that this should not be worked on at
>   the present time, and whether any of the dev-ref uploaders object to
>   the prospect of my unilaterally committing and uploading this
>   change.

> With regard to the second item, the question is whether it would be
> significantly more efficient to try to reuse the old scripts.

Yes, as long as we have a matching snapshot of Debian-SGML, it saves a
lot of time.  Usually, it is easier to work on XML than SGML if you want
to apply automated script.

> While I worked on the docbook->rST+Sphinx stage of converting
> debian-policy, I was not involved in the Debian-SGML->docbook stage,
> so I need others' input on that.

Hold on a bit.  Let me check few things.

> If I end up writing a new conversion script, I don't expect to be able
> to produce a program that will every single bit of markup right, but
> one that would get most of the way there.  This approach worked well
> for Policy when we converted that to rST+Sphinx in 2017.

Yes and no.  You didn't have translation.

Now that we have nice build script from reST, we should think to
automate as much.

Osamu

Bug#905909: README.md: Formatting and publication to www.debian.org

[Osamu Aoki]

Package: src:debian-policy
Version: 4.2.0.1
Severity: normal
Tags: patch

README.md of debian-policy at salsa doesn't show indexed list as
expected.

Also, it doesn't provide information on how it get published to
www.debiasn.org site to track down issues.

This github style MD s a bit tricky but my commit
  baea79f ("Format ...", 2018-08-11)
at
  https://salsa.debian.org/osamu/policy
should fix issues in "Making a release".

Now number goes 7 8 9 10 11 instead of 7 1 2 3.

See the bottm of these web pages.
  https://salsa.debian.org/dbnpolicy/policy
  https://salsa.debian.org/osamu/policy

Please merge my changes after squishing history :-)

Osamu
-- System Information:
Debian Release: buster/sid
  APT prefers testing
  APT policy: (500, 'testing'), (10, 'unstable')
Architecture: amd64 (x86_64)

Kernel: Linux 4.17.0-1-amd64 (SMP w/4 CPU cores)
Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8), 
LANGUAGE=en_US:en (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash
Init: systemd (via /run/systemd/system)
LSM: AppArmor: enabled

Bug#813471: Seeking seconds for patch to permit some network access to localhost

[Osamu Aoki]

On Sun, Jul 22, 2018 at 05:19:14PM +0800, Sean Whitton wrote:
> control: tag -1 +patch
> 
> Hello,
> 
> Here is a patch, for which I am seeking seconds, that tries to capture
> the points raised by Osamu, Guillem and Paul without getting into
> legalese -- Bill has a point.  In particular, I think we can trust
> package maintainers to interpret "started by the build" sensibly.
> 
> Discussion by Ian and Simon cloned into a separate bug and continued
> there.  Gunnar's discussion should be a separate bug, so setting it
> aside for now.
> 
> > diff --git a/policy/ch-source.rst b/policy/ch-source.rst
> > index 9e7d79c..34c90b3 100644
> > --- a/policy/ch-source.rst
> > +++ b/policy/ch-source.rst
> > @@ -278,7 +278,8 @@ non-interactive. It also follows that any target that 
> > these targets
> >  depend on must also be non-interactive.
> >  
> >  For packages in the main archive, no required targets may attempt
> > -network access.
> > +network access, except to services on the build host that have been
> > +started by the build, via the loopback interface.
> >  
> >  The targets are as follows:
> >  


Looks good to me.

Seconded

Osamu 

Re: debian/upstream/signing-key.asc in policy 4.1.0

[Osamu Aoki]

Hi,

On Sun, Aug 27, 2017 at 08:51:49PM -0300, Henrique de Moraes Holschuh wrote:
> On Wed, 23 Aug 2017, Russ Allbery wrote:
> > Note that this Policy language is carefully written to make it perfectly
> > fine for uscan to support all the things it currently supports, since it
> > only talks about what Policy recommends the maintainer does.  So don't
> > feel any obligation to change what uscan is doing on Policy's account
> > here.
> 
> Actually, the text in 4.1.0.0 might be doing too much.  It reads:
> 
> "If the upstream maintainer of the software provides OpenPGP signatures
> for new releases, including the information required for "uscan" to
> verify signatures for new upstream releases is also recommended. To do
> this, use the "pgpsigurlmangle" option in "debian/watch" to specify
> the location of the upstream signature, and include the key or keys
> used to sign upstream releases in the Debian source package as
> "debian/upstream/signing-key.asc".
> 
> IMO, it should either not be mandating uscan internals, or it should be

In principle, you comment is a very reasonable one.

> very clear about the exact subset of stuff we can use in debian/watch
> (version, etc).  For example, I'd rather use opt="..., pgpmode=auto,..."
> instead of explicitly hardcoding a "pgpsigurlmangle".

The new pgpmode=auto and pgpmode=previous have bugs and fail to function
smoothly ---  #873289 #852537  Excuse me for these bugs.  The fixes have
been committed to git.  I am hoping the next upload of devscripts (and
its backport) will fix them.  So "pgpsigurlmangle" is the only good way
at this moment.
 
> IMHO, just drop everything from "To do this..." to the end of that
> paragraph entirely.  HOW one gets "uscan" to fetch and check upstream
> signatures is a job for the uscan(1) manpage.  Alternatively, just
> mention "debian/watch", and to refer to the uscan documentation in
> package "devscripts".

Once pgpmode=auto becomes noise free, this should be the preferred
choice.  It will be nice to address #833012, too, using s/\?/.asc?/ etc.
to make it really default one.

So for now, the policy text is better for me.

> OTOH, if we really need to mandate a specific level of debian/watch
> support, the current text in policy needs work: it doesn't even tell me
> whether I can use version=3 (supported in oldstable), or version=4
> (supported in oldstable-backports and stable), for example...

The uscan version=3/version=4 difference is not much about enhanced
mangling rules.  It's about how uupdate is invoked and how uupdate
creates the updated source tree.  version=4 uses dpkg-source as back-end
and capable of generating multi-upstream tarball.

If you use new uscan, even with a watch file marked as version=3, it has
access to the enhanced mangling rules.

Osamu

Re: debian/upstream/signing-key.asc in policy 4.1.0

[Osamu Aoki]

Oops.

On Sun, Aug 27, 2017 at 12:55:26AM +0900, Osamu Aoki wrote:
> Hi,
> 
> On Wed, Aug 23, 2017 at 09:27:25AM -0700, Russ Allbery wrote:
> > Osamu Aoki <os...@debian.org> writes:
> > > The updated uscan will support debian/upstream/signing-key.asc only and
> > > internally convert it /signing-key.gpg.  I will make uscan to
> > > convert other formats to this policy compliant *.asc.  Also make noise
> > > to the maintainer to push them to policy 4.1.0
> > 
> > Note that this Policy language is carefully written to make it perfectly
> > fine for uscan to support all the things it currently supports, since it
> > only talks about what Policy recommends the maintainer does.  So don't
> > feel any obligation to change what uscan is doing on Policy's account
> > here.
> 
> Maybe I should have been a bit careful with my words:
> 
> The updated uscan will support debian/upstream/signing-key.asc only as
> the recommended keyring.  It will accept other historic keyrings but
> also internally converts them to /signing-key.gpg to guide

Of course:
  /signing-key.asc

> people to the new recommended format with some reminder noise.

Now committed to git.

Osamu

Re: debian/upstream/signing-key.asc in policy 4.1.0

[Osamu Aoki]

Hi,

On Wed, Aug 23, 2017 at 09:27:25AM -0700, Russ Allbery wrote:
> Osamu Aoki <os...@debian.org> writes:
> > The updated uscan will support debian/upstream/signing-key.asc only and
> > internally convert it /signing-key.gpg.  I will make uscan to
> > convert other formats to this policy compliant *.asc.  Also make noise
> > to the maintainer to push them to policy 4.1.0
> 
> Note that this Policy language is carefully written to make it perfectly
> fine for uscan to support all the things it currently supports, since it
> only talks about what Policy recommends the maintainer does.  So don't
> feel any obligation to change what uscan is doing on Policy's account
> here.

Maybe I should have been a bit careful with my words:

The updated uscan will support debian/upstream/signing-key.asc only as
the recommended keyring.  It will accept other historic keyrings but
also internally converts them to /signing-key.gpg to guide
people to the new recommended format with some reminder noise.

> That said, as discussed elsewhere, I'm a huge fan of there being only one
> way to do something like this, with some easy tools to convert other
> methods into that one method.  It reduces everyone's cognitive load in the
> future.

Yes.

Osamu

debian/upstream/signing-key.asc in policy 4.1.0

[Osamu Aoki]

Hi,

After all the discussion, Policy 4.1.0 goes as:

| 4.11. Optional upstream source location: debian/watch¶
| 
| This is an optional, recommended configuration file for the uscan
| utility which defines how to automatically scan ftp or http sites for
| newly available updates of the package. This is also used by some Debian
| QA tools to help with quality control and maintenance of the
| distribution as a whole.
| 
| If the upstream maintainer of the software provides OpenPGP signatures
| for new releases, including the information required for uscan to verify
| signatures for new upstream releases is also recommended. To do this,
| use the pgpsigurlmangle option in debian/watch to specify the location
| of the upstream signature, and include the key or keys used to sign
| upstream releases in the Debian source package as
| debian/upstream/signing-key.asc.
| 
| For more information about uscan and these options, including how to
| generate the file containing upstream signing keys, see uscan.

Please note few things which I failed to share:

The current uscan supports both 
 debian/upstream/signing-key.asc
 debian/upstream/signing-key.pgp

Now, if debian/upstream/signing-key.asc is used, uscan converts it to
/signing-key.gpg by gpg for use with gpgv to check
signature.  (I think the same goes with dpkg-source).  It looks extra
CPU power waste but not a big deal. I do this conversion since no
documentation mention keyring can be ascii armored for gpgv.

The updated uscan will support debian/upstream/signing-key.asc only and
internally convert it /signing-key.gpg.  I will make uscan to
convert other formats to this policy compliant *.asc.  Also make noise
to the maintainer to push them to policy 4.1.0

Regards,

Osamu

Re: Upstream Tarball Signature Files

[Osamu Aoki]

Hi,


On Fri, Aug 18, 2017 at 12:02:27PM +0200, Guillem Jover wrote:
..
> Adding support for more signature formats or filename variations is
> not hard, but it increases the amount of those extensions and perhaps
> the additional sanity checks we have to support and perform on them on
> multiple tools, etc. It would also require waiting at least once more
> release cycle until they can be used.

I just commited uscan/mk-origtargz support of these.

It will be nice dpkg can support both
 foo.tar.gz
 foo.tar.gz.asc
or 
 foo.tar.gz
 foo.tar.asc (signature on uncompressed)
combinations.

There are upstream releasing in these format.

More nasty one is releasing foo.tar.gz with "gpg -s" w/o -b as
foo.tar.gz.sig or "gpg -sa" as foo.tar.gz.asc.  I have no idea how to
extract signaturefile from non-detached signature.  That's remaining
task but a rare case.

Osamu

How to handle upstream tarbell signature

[Osamu Aoki]

Hi,

I was trying to update uscan and realized few problems which are not
addressed by the discussion here.  There are many things to consider.


On Fri, Aug 18, 2017 at 02:43:58PM +0200, Mattia Rizzolo wrote:
> On Fri, Aug 18, 2017 at 07:48:24AM -0400, Daniel Kahn Gillmor wrote:
> > I confess that i've been taking the boring/silly/cheating way out and if
> > upstream ships a detached binary signature as foo-1.2.3.tar.gz.sig, i've
> > just been manually renaming it to foo_1.2.3.orig.tar.gz.asc (without
> > even converting its contents to ASCII-armored form) and the rest of the
> > toolchain seems to just happily accept it -- it'd be even nicer if dpkg
> > and/or uscan was to normalize the contents to match the file extension.
> 
> That's because TTBOMK there is *nothing* atm actually validating that
> file, and AFAIK (please correct me if I'm wrong) dpkg-source just picks
> up whatever file, no matter the contents.

If the watch file is properly configured, uscan verifies signature.
You should have upstream keyring stored in

   debian/upstream/signing-key.asc

> > Lastly, it's conceivable that we might want to take an already-armored
> > .asc, and "launder" the armor, to stabilize it (e.g. stripping
> > non-cryptographically-relevant comments, other weird OpenPGP packets,
> > etc, which could all be stuffed into the detached signature).
> 
> I'd love if something did this for me, pretty much like I'd love
> something like that does a pretty output to debian/upstream/signing-key
> like
> https://sources.debian.net/src/inkscape/0.92.2-1/debian/upstream/signing-key.asc/
> (that's
> https://anonscm.debian.org/git/reproducible/misc.git/tree/dump-gpg-keys.sh)
> 
> IOW: Guillem: I second merging that sig→asc converter into dpkg-source!
> :)

1. There are different ways of signature
   * files used
 * detached signature   gpg -sb   (easy)
 * non-detached signature   gpg -s(No answer)
   * format used
 * binary (.gpg, ...) (easy but who convert)
 * ascii  (.asc)  (easy)

2. What to do if upstream is repacked.
   * uscan can confirm but where to put the result in case it is
 repacked.
   * If we leave upstream keyring at debian/upstream/signing-key.asc, it
 has no value to the generated Debian packages.  (A new *.asc can be
 added by maintainer but that's its useless since we upload with
 signed *.dsc.  We need to look into debian/copyright to see if this
 is repacked or not.  But people may use different way to repack.
 So it is confusing to have keyring.  There should be clear way to
 identify if it is repackaged or not easily.) 

Does anyone have clear idea on "gpg -s" case for 1 and answer for 2?

These affects how I write uscan.

Osamu

Re: Upstream Tarball Signature Files

[Osamu Aoki]

Hi,

On Fri, Aug 18, 2017 at 12:08:02PM +0200, Guillem Jover wrote:
> Hi!
> 
> On Wed, 2017-08-16 at 00:22:43 -0700, Paul Hardy wrote:
> > On Tue, Aug 8, 2017 at 1:48 AM, Guillem Jover  wrote:
> > > On Mon, 2017-08-07 at 20:26:41 -0700, Paul Hardy wrote:
> > > > Also, where signature files are desired, I think it would be beneficial
> > > > to also accept binary ".sig" files...
> > >
> > > There is no need for that, you can convert from ASCII armored to
> > > binary signatures and the other way around easily. For example to
> > > convert from .sig to .asc you can do the following:
> > >
> > >   $ gpg --output - --enarmor unifont_upper-10.0.05.ttf.sig | \
> > > sed -e 's/ARMORED FILE/SIGNATURE/;/^Comment:/d' > \
> > > unifont_upper-10.0.05.ttf.asc
> > >   ...
> > >
> > > This could be done automatically as part of uscan, so you'd not even
> > > need to do it manually!
> 
> > Would you consider doing this conversion in a separate shell script as part
> > of dpkg-dev (for example, named "sig2asc")?  Then the script could be run
> > from the command line, and uscan also could invoke it.  If you would accept
> > that, I could write a proposed shell script with a man page for you and
> > file them as patches in a bug against dpkg-dev or mail them to you
> > privately.
> > 
> > I am the GNU Project maintainer for Unifont.  I build the GNU upstream
> > version and the Debian version with one higher-level "make" command at the
> > same time.  So I would not use uscan for OpenPGP format conversion; I only
> > use it in my debian/watch file.
> > 
> > With a separate shell script in place, maintainer documentation could be
> > updated to mention it.  After that, wording for a Policy change concerning
> > upstream signatures could be crafted that would refer to that capability.
> 
> Hmmm, I've been thinking about this a bit, and perhaps it would be
> better if dpkg-source auto-converted any .sig binary signature into
> an .asc ASCII armored one when generating the source package (as long
> as there is no pre-existing .asc file).

If uscan/uupdate can off-load this task to dpkg-source, it's great for
me. They are already too much functionalities in them.

Important thing is (as I already changed my mind as I posted) to keep
this signature file format of the source package to be as uniform as
possible.  Tools such as DAK can support this new source file format
addition with least work.

> This has the advantage of not
> requiring devscripts to be installed, preserves compatibility with
> stable dpkg-source and DAK so it can be used right away, and allows
> us to keep using a single signature format. I've got code doing that
> now, which I can merged for 1.19.0, I guess the only possibly
> contentious point is that this might seem like doing too much magic
> from within dpkg-source?

Wherever we make conversion, it's a magic.  We need to get things
simple across system somehow.

No objection from me.

Anyway gnupg is recommends for dpkg-dev (dpkg-source) already.  So if
gnupg is missing, just spit out warning.

Osamu
 

Re: Upstream Tarball Signature Files

[Osamu Aoki]

Hi,

On Mon, Aug 14, 2017 at 10:13:10AM -0700, Russ Allbery wrote:
> Henrique de Moraes Holschuh  writes:
> 
> > We do when the binary sig is small enough to be stored along with the
> > inode, instead of requiring an entire filesystem block (4KiB), and the
> > armored signature is not small enough for that :-( Of course, this
> > really depends a lot on the filesystem, etc.
> 
> I'm not sure what signatures you're looking at.  Maybe ones with lots of
> separate signers?  A typical *.asc file with one signer is about 500
> bytes.
> 
> > May I humbly suggest that, *if* a change is going to be made, we switch
> > to ".sig" (binary) and ".sig.asc" (armored), or .sig.gpg / sig.gpg.asc?
> > As in "let's not overload .asc to mean armored signature, when it only
> > means ASCII text"...
> 
> Note that I'm arguing for no change, just documenting the existing support
> for *.asc upstream signatures.  This will imply that anyone who wants to
> include an upstream signature that's provided in *.sig format will need to
> convert it to *.asc, but that's not a *change*.  That's the current state
> of the archive.

Very good points.  I changed my mind a bit.

Basically, its better to have uniform rules for format so all associated
tools become simple.  Tools like uscan may accept any signature format,
but the tools at the level of dpkg and archive maintenance tools should
be simple.

I like to use *.asc as signature file.  (Uscan may convert)

Also, maybe policy just mandate debian/upstream/signing-key.asc for key
ring.

Osamu

Bug#871525: debiandoc-sgml deprecated, use rst or docbookxml

[Osamu Aoki]

Source: python3-defaults
Version: 3.5.3-3
Severity: important

As reported in https://bugs.debian.org/870820 and getting very positive
feedback at DEBCONF17 after migrating Debian Policy to DocBookXML,
debiandoc-sgml will be removed from the archive at buster+{0,1}. I am sending
reminder to packages which still uses this package.

The offending SGML source is converted to XML using "debiandoc2dbk -1" command.
Also "pandoc -f doocbook -t rst" can convert docbookxml into pandoc.

If you wish to move this to policy, please talk to them.

Also, since this is Python, why not RST?

So please replace it and use the actively maintained XML/RST tool chain.

Auto converted file attached.  (You may need to do manual fix.)

Osamu



-- System Information:
Debian Release: 9.1
  APT prefers stable
  APT policy: (500, 'stable')
Architecture: amd64 (x86_64)

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


http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd; [


]>



Debian Python Policy




Neil 
Schemenauern...@debian.org
Matthias 
Klosed...@debian.org
Gregor 
Hoffleitfli...@debian.org
Josselin 
Mouettej...@debian.org
Joe 
Wreschnigpi...@debian.org


version 0.4.1.0






This document describes the packaging of Python within the Debian GNU/Linux
distribution and the policy requirements for packaged Python programs and
modules.



1999, 2001, 2003, 2006Software in the Public 
Interest


This manual is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later
version.


This is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.  See the GNU General Public License for more details.


A copy of the GNU General Public License is available as
/usr/share/common-licences/GPL in the Debian GNU/Linux
distribution or on the World Wide Web at http://www.gnu.org/copyleft/gpl.html;>The GNU Public Licence.


You can also obtain it by writing to the Free Software Foundation, Inc., 59
Temple Place - Suite 330, Boston, MA 02111-1307, USA.






Python Packaging
Versions

At any given time, the package python
will represent the current default Debian Python version.


The default Debian Python version should alway be the latest stable upstream
release that can be integrated in the distribution.


Apart from the default version, legacy versions of Python or beta versions of
future releases may be included as well in the distribution, as long as they
are needed by other packages, or as long as it seems reasonable to provide
them.  (Note: For the scope of this document, Python versions are synonymous to
feature releases, i.e.  Python 2.0 and 2.0.1 are subminor versions of the same
Python version 2.0, but Python 2.1 and 2.2 are indeed different versions.)


For any version, the main package must be called pythonX.Y.


The set of currently supported python versions can be found in
/usr/share/python/debian_defaults.



Main package

For every Python version provided in the distribution, the package pythonX.Y
shall comprise a complete distribution for deployment of
Python scripts and applications.  The package includes the binary
/usr/bin/pythonX.Y
and all modules of the upstream Python distribution.


Excluded are any modules that depend on non-required
packages, they will be provided in separate packages.  Some tools and files for
the development of Python modules are split off in a
separate package pythonX.Y-dev.
Documentation will be provided separately as well.


At any time, the python package must
contain a symlink /usr/bin/python to the the appropriate
binary
/usr/bin/pythonX.Y.
The python package must also depend on
the appropriate pythonX.Y
to ensure this binary is installed.  The version of the python package must be greater than or equal to
X.Y and smaller than
X.Y+1.



Python Interpreter
Interpreter Name

Python scripts depending on the default Python version (see ) or not depending on a specific Python version should use
python (unversioned) as the interpreter name.


Python scripts that only work with a specific Python version must explicitly
use the versioned interpreter name
(pythonX.Y).



Interpreter Location

The preferred specification for the Python interpreter is
/usr/bin/python or
/usr/bin/pythonX.Y.
This ensures that a Debian installation of python is used and all dependencies
on additional python modules are met.


If a maintainer would like to provide the user with the possibility to override
the Debian Python interpreter, he may want to use /usr/bin/env
python or /usr/bin/env
pythonX.Y.
However this is not advisable as it bypasses Debian's dependency checking and
makes 

Re: Upstream Tarball Signature Files

[Osamu Aoki]

Hi,

On Tue, Aug 08, 2017 at 10:48:08AM +0200, Guillem Jover wrote:
...
> On Mon, 2017-08-07 at 20:26:41 -0700, Paul Hardy wrote:
> > Also, where signature files are desired, I think it would be beneficial to
> > also accept binary ".sig" files as an alternative to ".asc" files, for
> > example as produced with "gpg -b".
> 
> There is no need for that, you can convert from ASCII armored to
> binary signatures and the other way around easily. 

True.  But why you want to limit to one format between .sig and .asc?

For example, uscan accepts either one when it downloads and verifies the
downloaded tarball and signaturefile.{asc,pgp,gpg,sgn,sign} with the
keyring stored in debian/upstream/signing-key.{pgp,asc}.  Why not do the
same?

If you accepts, uscan's job is creating symlink only to fix the newly
requested bug.

Please note we are more relaxed on what upstream does but what packager
does is limited to debian/*.pgp only (no gpg, sgn sign) at this moment.
(Maybe I can relax it if someone requests it with good reason.)

> Although, some of those .sig files on the GNU site are actually ASCII
> armored signatures (c.f. hello).

The uscan manpage says it accepts 4 extensions while it is accepting 5
extensions now.  I will fix it.

Osamu

Re: Upstream Tarball Signature Files

[Osamu Aoki]

Hi,

On Mon, Aug 07, 2017 at 08:26:41PM -0700, Paul Hardy wrote:
...
> Making changes to debian-policy (if deemed appropriate) to allow upstream
> binary signature files would affect at least lintian, dpkg-dev, uscan, and
> Debian maintainer guides.

You should mean one of:
 Debian Developer's Reference
 Debian New Maintainers' Guide
 Guide for Debian Maintainers
 
> Such signature files are discussed in bug #870069 for lintian and #727096 for
> uscan.

Now I understand the context/motivation behind the new #870281 uscan bug
report.

Osamu

Bug#175064: DocBook XML conversion is read with this script

[Osamu Aoki]

Hi,

Thanks for moving my 6 year old patch snippets/idea into real action.

On Sun, Jan 15, 2017 at 04:54:32PM +0100, Guillem Jover wrote:
...
> 
> On Sat, 2017-01-14 at 21:30:14 +, Simon McVittie wrote:
> > On Sat, 14 Jan 2017 at 11:32:09 -0800, Russ Allbery wrote:
> > > Bill Allombert  writes:
> > > > I am concerned that DocBook is much too complex to be used for Debian
> > > > policy.  We need to people to write patches without trouble and we do
> > > > not have many editors available for fixing the XML. Debiandoc-SGML
> > > > virtue is that it is simple.
> 
> > > They seem essentially identical to me?  We've had copyright-format in the
> > > Policy distribution for a while, and it's never seemed any different to me
> > > (as someone not horribly familiar with XML markup) from editing Policy.

DocBook can be complex if you use some rarely used tags.  But you don't
need to do that.

The DocBook XML files generated by Guillem's script only use very
limited subset of tags.  I know this since I wrote core of the
conversion engine.   For policy, it is wise not to use fancy new tags
unless it is absolutely needed and the future edits should limit the use
of new XML tags.

Subversion's documentation is insightful.  DocBook lite is what they
use.

 
http://svn.apache.org/repos/asf/subversion/branches/1.6.x-r1138375/doc/tools/readme-dblite.html

> Yeah, pretty much. And there are way more tools to handle DocBook than
> DebianDoc-SGML; linters, editors, converters, etc. more documentation
> and people that will know DocBook too.

Also, DocBook format is very stable.  ASCIIDOC and other markup
languages are convenient if you use it once or for a short document.
But it will bite you when they change implementation details.  I have
been bitten by ASCIIDOC changes.

(I use ASCIIDOC for documentation as a way to easily create legal XML
data)

> > > The alternative, I guess, would be to use Markdown for the whole thing,
> > > but I think it's worthwhile to have sections and internal links and a bit
> > > more formatting than Markdown gives us.
> 
> While I like Markdown very much, I've found in many situations that it
> is very limiting when you want to start doing more interesting markup
> and formatting. :(
> 
> > asciidoc, then? Or Markdown with pandoc extensions?
> > 
> > asciidoc is another wiki-like language, but has semantics defined in
> > terms of Docbook rather than HTML.
> > 
> > Pandoc's Markdown dialect includes footnotes and explicit or implicit
> > anchors in headings.

Pandoc should be able to convert DocBook XML into Markdown or anything,
in theory.

But Markdown has too many dialects depending on which processing
infrastructure you use, results vary.

So DocBook is a neutral ground.  Exim documentation experience tells me
that these non-XML markup saves typing but its not a good idea for long
term solution if many people are involved.
...
 
> > > Anyway, my understanding (see earlier messages in this bug) is that the
> > > maintainer of DebianDoc-SGML is actively trying to transition people away

YES I do.  Once Policy is converted, I will probably orphan/RFA this package.

(Maybe FAQ is the remaining one to be converted but with this updated
script combination, that conversion is coming soon.)

...

Osamu

Bug#813471: network access to the loopback device should be allowed

[Osamu Aoki]

On Wed, Feb 03, 2016 at 12:22:14AM +0100, Guillem Jover wrote:
> Hi!
> This is probably too restrictive too. It would not allow local access
> through TAP device or other similar things. It might be better to just
> say something like:
> 
> | For packages in the main archive, no required targets may attempt
> | network access outside the current machine.
> 
> or something along those lines.

I agree with you.

Osamu

Bug#813471: network access to the loopback device should be allowed

[Osamu Aoki]

Package: debian-policy
Severity: normal

Bug #770016 "Clarify network access for building packages in main"
was about not downloading files via network.  This created new lines in
4.9 as:

| For packages in the main archive, no required targets may attempt
| network access.

This is too restrictive.

The build target of devscripts has several tests testing http acess to
the http server on the loopback device.

But the above new policy lines may be considered to prohibit this.

I thought the this should be more like:

| For packages in the main archive, no required targets may attempt
| network access except for the access to the loopback device.

I understand downloading from Debian or non-Debian web site is bad for
buildd but network operation to the loopback device (like http access)
should be OK.

-- System Information:
Debian Release: stretch/sid
  APT prefers testing
  APT policy: (500, 'testing'), (98, 'unstable')
Architecture: amd64 (x86_64)

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

Bug#659070: bad internal links on www.debian.org for developers-reference

[Osamu Aoki]

Hi,

I knew someone already complained this :-) CCed.

When I wanted to add several web pages from packages to work nicely on
the www.debian.org with the content negotiation, I thought this kind of
things have working precedence with a proper script.   Looking at the
developers-reference case which should have such solution, it is missing
required work.  There is no fix-up done.  Dah!

This is relatively easy problem.

cron script needs a bit more sed/tr work.

If anyone else is working on this, let me know.  In the meantime, I will
try creating generic solution without touching *.deb building
procedures.

I think I can fix this ... stay tuned :-)

Osamu
PS: Charles, you are the only committer to the cron script except me.  I
hope you do not mind making some refactoring of code around 
 ssh://git.debian.org/git/debwww/cron.git parts/7doc


-- 
To UNSUBSCRIBE, email to debian-policy-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Archive: https://lists.debian.org/20150612131940.GA9993@goofy.local

Re: improvements to the Developers Reference maintenance workflows?

[Osamu Aoki]

Hi,

I wonder if the problem is format or content provider.

On Thu, Jun 19, 2014 at 09:05:17AM +0200, Raphael Hertzog wrote:
 (adding debian-doc to the cc)
 Hi,
 On Thu, 19 Jun 2014, Paul Wise wrote:
  Some of you may be aware there has been a discussion about devref on
  debian-private and debian-project, the threads started here:
  
  20140613131135.ga7...@x61s.reliablesolutions.de
  https://lists.debian.org/20140618120859.ga7...@jwilk.net
 
 Yes, I saw it and wanted to chime in... but I did not find the time
 and motivation and wanted to see where the discussion would lead.
 
  Switch to a different documentation format that more people are able to
  write, this probably too much work to be useful though.
 
 I don't think this is the real blocker. People should be free to submit
 content without markup (or with wiki-like markup), it's easy to integrate
 the content and add the small bits of docbook markup.

True.  (Only question is who has time and motivation to do this.)

If you are serious about exporting to DocBook XML, you may need to
assess which wiki platform to use and write some XSLT scripts etc.
(ikiwiki + git + XML converter ... seems good choice over moinmoin)

  Switch from svn to git. Many people prefer git to svn, this might
  increase the amount of people willing to contribute. 
 I would definitely welcome this, I'm using git-svn anyway currently.

 The debian-doc group uses svn for historic reasons but I don't think
 that anyone would oppose switching the devel-ref (which has always been
 treated in a special way). I don't know if the debian-doc alioth project
 granted commit rights to debian developers by default. But, if not, we
 should certainly do it.

Many active DDP documents are in git repo these days.  You can set it up
in ddp directory, if you wish.

  Publish directly to the website on each git push. This would make the
  devref copy on the website less stale. An alternative might be weekly or
  monthly releases to the archive.
 
 We used to do this but:

Yes.
 
 1/ the www team wanted to get rid of this because maintaining a proper
 build environment was causing regular problems (eg due to version skew
 between stable (the www build environment) and unstable (the package build
 environment)).
 
 2/ the supplementary delay was seen by some people as a good thing so that
 changes can be better reviewed before being pushed to the wide public
 
 3/ some believe that the content of the package is as important as the 
 content of the
 website and we should release more often to avoid those delays

4/ Translation is in sync using PO4a (which seems to be lacking in wiki
available as wiki.debian.org, yet.)

 So yes, we should do monthly releases (weekly is a bit too much IMO).
 
  Add an ACL so that all Debian members are able to commit (or move to
  collab-maint). This would lower the bar for contributions, allow trivial
  issues to be fixed easily and reduce change latency.
 
 I have no problem with this but others have had with this way of working.
 
 With Andreas Barth, while we were disagreeing about the way to maintain
 this package, we agreed that direct commit was not really acceptable and
 that each patch should be sent to the BTS for review. Explicit ACK or
 lack of opposition could then be used to commit the changes.

The work flow of wiki and this kind of resolution does not go well.
 
 Steve Langasek was also strongly in favor of some prior review because the
 document ought to define the best practices for the project and changes
 without buy in from the project at large would be detrimental.

Quite understandable.

  Call for help so that more people get involved and more issues get
  fixed. This could be a single mail to d-d-a or a DevNews entry. This
  should probably only happen after some improvements are made.
 
 Yes.

Wait a moment, what we need is not to work on format conversion or new
system but the contents used for the dev-ref.

More practical thing is people to set up proposal pager organized to
match dev-ref chapters with alternative and additional contents.  (This
could have been done but I did not see such activity to supplement
dev-ref except for some multi-arch transition and compiler flag
updates.)

Then file bug requests to maintainers.  This can be done now without any
new system.

As long as it is well known place, people can always reference it as
secondary resource.  Wiki comes with ease of access but also comes with
many stale outdated pages as you know.  So the review and integration as
we see now is very valuable thing.

If a wiki chapter get big enough, we can add it to a new chapter.

If update of the dev-ref stalls and wiki pages grow big enough, making static
XML from it can be our task, then.

With the resource we see, I am a bit skeptical on spending resource to
new things like setting up wiki based platform while breaking somewhat
working iwork flow.  Of course, someone volunteer and execute this task,
I am happy him doing it.

Regards,

Bug#741269: tools: use GIT instead of CVS, Use cowbuilder instead od pbuilder-uml

[Osamu Aoki]

Package: developers-reference
Version: 3.4.11
Severity: normal
Tags: patch

Almost no one use CVS now.

Let's switch description to GIT.

Also, popcon for
  pbuilder  3500
  cowbuilder2000
  pbuilder-uml90

(I think upstream is focusing on cowbuilder used as backend of pbuilder.

So let's adjust text as attached.

Osamu

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

Kernel: Linux 3.13-1-amd64 (SMP w/8 CPU cores)
Locale: LANG=en_US.utf8, LC_CTYPE=en_US.utf8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash

developers-reference depends on no packages.

Versions of packages developers-reference recommends:
ii  debian-policy  3.9.5.0

Versions of packages developers-reference suggests:
ii  doc-base  0.10.5

-- no debconf information
diff --git a/developers-reference/tools.dbk b/developers-reference/tools.dbk
index 70514dc..22af3a3 100644
--- a/developers-reference/tools.dbk
+++ b/developers-reference/tools.dbk
@@ -212,17 +212,17 @@ packages.
 The following packages help with the package building process, general driving
 commanddpkg-buildpackage/command as well as handling supporting tasks.
 /para
-section id=cvs-buildpackage
-titlesystemitem role=packagecvs-buildpackage/systemitem/title
+section id=git-buildpackage
+titlesystemitem role=packagegit-buildpackage/systemitem/title
 para
-systemitem role=packagecvs-buildpackage/systemitem provides the
-capability to inject or import Debian source packages into a CVS repository,
-build a Debian package from the CVS repository, and helps in integrating
+systemitem role=packagegit-buildpackage/systemitem provides the
+capability to inject or import Debian source packages into a GIT repository,
+build a Debian package from the GIT repository, and helps in integrating
 upstream changes into the repository.
 /para
 para
-These utilities provide an infrastructure to facilitate the use of CVS by
-Debian maintainers.  This allows one to keep separate CVS branches of a package
+These utilities provide an infrastructure to facilitate the use of GIT by
+Debian maintainers.  This allows one to keep separate GIT branches of a package
 for literalstable/literal, literalunstable/literal and possibly
 literalexperimental/literal distributions, along with the other benefits
 of a version control system.
@@ -254,9 +254,8 @@ package's build-dependencies are correct, and to be sure that unnecessary and
 wrong build dependencies will not exist in the resulting package.
 /para
 para
-A related package is systemitem role=packagepbuilder-uml/systemitem,
-which goes even further by doing the build within a User Mode Linux
-environment.
+A related package is systemitem role=packagecowbuilder/systemitem,
+which speeds up the build process using COW filesystem on any standard Linux filesystem.
 /para
 /section
 

Bug#697039: debian-policy: cron scripts should obey similar rules as init scripts

[Osamu Aoki]

Package: debian-policy
Severity: wishlist

I have installed ikiwiki and configured it sometime ago.  I removed its
package recently but did not purge it I got noisy cron error
messages.  If the cron script was written in the way most other packages
checking the existence of the executable, this did not happen.  I do not
know where were the original cause (my error?) but this let me look into
the policy :-)

Some parts of the rules described under 9.3.2 Writing the scripts
 http://www.debian.org/doc/debian-policy/ch-opersys.html#s-writing-init
for init scripts such as the requirement to check the existence of
executables before their execution *must* be applied also to any
automatically starting scripts provided as conffile.  

Example of such conffiles of automatically starting scripts provided as
a part of a package are:
 * init scripts
 * cron scripts
 * power control scripts
 * pluggable device control scripts
 * ...

Also, this rule for the automatically starting scripts should also be
applied to ones generated by the package configuration helper.  Such
helper *should* generate scripts with the same care.

This prevents un-needed error log after the package removal without
purging.

In this respect, inserting a section just before 9.3 as new 9.3 Writing
the automatic scripts while copying most of the 9.3.2 contents except
for the parts of the start, stop, restart, and force-reload options
while mentioning The following rules for automatically starting scripts
provided as conffile must be followed. at the top or something similar,
will be a good idea.

The old 9.3.2 Writing the scripts and old 9.5 Cron jobs should be
updated to point to additional requirement for such scripts.

Osamu

-- System Information:
Debian Release: 7.0
  APT prefers unstable
  APT policy: (500, 'unstable'), (500, 'testing'), (10, 'experimental')
Architecture: amd64 (x86_64)
Foreign Architectures: i386

Kernel: Linux 3.7-trunk-amd64 (SMP w/8 CPU cores)
Locale: LANG=en_US.utf8, LC_CTYPE=en_US.utf8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash


-- 
To UNSUBSCRIBE, email to debian-policy-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Archive: http://lists.debian.org/20121231031018.GA22436@goofy.localdomain

Bug#666578: Fixed FTBFS in SVN

[Osamu Aoki]

Hi,

I just fixed this bug in subversion for developers-reference while
uploading new fixed version to archive for maint-guide.

I also tagged this as pending.

Who will be uploading this package.  

There are so many open bug reports.  There are 2 BTS reports with patch
but their validity has some open questions.  So I am not uploading this
package yet.

Osamu

PS: Somehow -submitter address seems to cause relay error with my ISP.



-- 
To UNSUBSCRIBE, email to debian-policy-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Archive: http://lists.debian.org/20120415121852.GA4123@localhost

Bug#629530: developers-reference: Japanese PDF available

[Osamu Aoki]

Hi,

On Sat, Jan 14, 2012 at 09:41:10AM +0900, Hideki Yamane wrote:
 Hi,
 
 On Thu, 12 Jan 2012 00:42:12 +0900
 Osamu Aoki os...@debian.org wrote:
Japanese PDF:

http://people.debian.org/~taffit/developers-reference-xetex/developers-reference.ja.pdf
  
  Japanese look good :-)
 
  Thanks, David :)
 
  Most of the contents looks good, however, some words are dropped.
  p68 and p.69  - (.orig) should be パッケージ名 - 開発元のバージョン (.orig) 
 
  Should I modify ja.po file for pdf?

I do not see that you have touched this part in the current SVN source.
It looks OK as PO source.

If this is not a problem in PO file, it may be font problem in build
environment.  Japanese Micho as installed may be lacking some italics
form requrested by the build script.  Please confirm.

As for translation of pristine you marked for FIXME, I agree it needs
to be translated uniformly.  May I suggest:
 * pristine source  : 原典のソース
 * pristine tarball : 原典の tarball 

Rationale: Pristine has a few listed meanings:
  - Original, pertaining to the earliest state of something:
-- 原典の (This imply no modification).
  - Pure, spotless, immaculate: 
-- 無垢の, 純朴な

Regards,

Osamu



-- 
To UNSUBSCRIBE, email to debian-policy-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Archive: http://lists.debian.org/20120114025404.GA6823@localhost

Bug#629530: developers-reference: Japanese PDF available

[Osamu Aoki]

Hi,

On Wed, Jan 11, 2012 at 12:25:23AM -0400, David Prévot wrote:
 tags 629530 pending
 thanks.
 
 Hi,
 
 Le 09/01/2012 12:49, David Prévot a écrit :
  Le 07/06/2011 08:56, Osamu Aoki a écrit :
 
  If you move this build this with XeTeX (specifically xelatex), this
  problem goes away.
  
  Indeed, I just rebuilt it with XeTeX and it works:
  
  http://people.debian.org/~taffit/developers-reference-xetex/developers-reference.pdf
 
 The file has been update, keeping its usual style (thank to Osamu for
 the maint-guide build process, and the explanations).
 
  Japanese PDF:
  
  http://people.debian.org/~taffit/developers-reference-xetex/developers-reference.ja.pdf

Japanese look good :-)

One note on content such as translation availability in page ii.

Any local link to file will cause problem these days for PDF and even
URL links.  So source needs to avoid such link.

 Updated too, so it now looks like the English and other already
 available translations (German and French). Hideki, Osamu, thanks in
 advance if you could confirm that the built document is OK.


Osamu




--
To UNSUBSCRIBE, email to debian-policy-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Archive: http://lists.debian.org/2012054212.GA4842@localhost

Bug#629530: developers-reference: PDF code example has wrong U+2019 for '

[Osamu Aoki]

Hi,

Hmmm... David, you beat me on making this happen :-)

Merci Beaucoup!

On Tue, Jan 10, 2012 at 08:26:13AM +0100, Raphael Hertzog wrote:
 Hi,
 
 On Mon, 09 Jan 2012, David Prévot wrote:
  As you may have noticed, the English document looks different: I quickly
  copied and pasted part of the maint-guide build system (the xslt
  directory is directly copied from there, and probably needs to be
  adapted to keep the current look), in order to build the Japanese PDF:
 
 Why did you have to do this change? Was it not enought to just add
 --backend=xetex?

For English, yes.  I forgot exactly how ...  I see ...  You need to
specify non-latin TTF fonts etc.  needed for CJK languages.   Also
Germans want their latex hyphnation specified.  I added latex
customization for hyphnation and font embedded into latex code using
plug-in xslt code.  These are required but minor customization.  I do
not think codeing style is elegant but works.  The work is done by
--backend=xetex to build pdf.

Oh, my makefile may not be safe for large -j value.  So there are
rooms to improve but we run make with -j1 or so.  So for now its OK.

(In squeeze, there were some build breakage for Debian Reference.  It
was some xelatex codes for table.  I gave up.  I was going to look into
this after the release but have not done so yet. I have been doing other
things such as input method packaging...  developer's reference is
simpler and this should be easier to build.)

 Doesn't that change also change the build dependencies?

Yes.  Just as I did for maint-guide.

  Since the Japanese translation is now complete, it would be nice if we
  could upload the package with the Japanese PDF once properly solved this
  issue (keeping the English document look too). Unless some more stuff
  needs to be addressed regarding the text, can I poke the German
  translator in order to upload an up to date package soon (within ten days)?
 
 Sure.

Yes, please.
 
 Cheers,

My big todo is to build all these DDP related packages under some
chroot.

  testing (monthly snapshot, updated when chroot installation is RC free
   excluding ones admin allow.)
  unstable

I think this should be good testing bed for tetex and other text
processing system.

Osamu



--
To UNSUBSCRIBE, email to debian-policy-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Archive: http://lists.debian.org/20120110123949.GA4990@localhost

Bug#175064: DocBook XML conversion is read with this script

[Osamu Aoki]

Hi,

Thanks for your help.

On Mon, Apr 25, 2011 at 05:25:31AM -0500, Jonathan Nieder wrote:
... 
 . Sometimes the spacing around closing tags looks unidiomatic, as in
 
   ... The detailed
   procedure for gracefully orphaning a package can be found in the Debian
   Developer's Reference (see xref linkend=related/ ).  /para 
 /footnote
 
   The extra space carries over to the rendered HTML, too.  Is that
   intentional?
 
 . Quotation marks were lost, for example in “Originally called Debian
   GNU/Linux Policy Manual, ...” at the start of the policy manual.
 
 . Aside from the quotation marks and spaces, I couldn't find any
   artifacts.  Seems like a good conversion.

I found the root causes of these and fixed them and uploaded debiandoc-sgml
1.2.24 .

I am busy with maint-guide at this moment but wil consider making
conversion available later.

Osamu





-- 
To UNSUBSCRIBE, email to debian-policy-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Archive: http://lists.debian.org/20110502131918.ga4...@debian.org

Re: [PATCH] Specify policy for use of revision IDs in version numbers

[Osamu Aoki]

Hi,

On Sat, Apr 30, 2011 at 03:51:15PM -0700, Russ Allbery wrote:
 Ben Hutchings b...@decadent.org.uk writes:
 
  + p
  +   The upstream version number must not include a non-linear
  +   revision ID or hash, since it cannot help in ordering
  +   versions and it tends to result in very long version
  +   numbers and filenames.  This information may be recorded
  +   in the changelog instead.
  + /p

It is a bit detailed and lacks limitation for length but I think it is a
good start.

The above goes to as 3.2.2 as I understand.  We already have 3.2.1
Version numbers based on dates and fits nicely into the context.

Let's add this.

 I don't think it's Policy's place to tell people that they can't use
 hashes because they *might* result in long version numbers.  They usually
 don't.

This is another topic.  I do not think everyone agreed yet to a
particular set of numbers.  The more I looked into this issue, I think
followings are the possible numbers:

 * package file name for normal uploads: 90 characters (must)
   - rationale: UCS-2 requirement etc.
   - current longest is 76 chars.
   - this number is ready for policy.

 * package name length =40 (must:   99.8% qualifies)
 * package name length =30 (should: 98.3% qualifies)
   - aptitude field length default

normal version length withour special extension such as +nmu? +b? ...
should be:

 * version length =30 (must:   99.9% qualifies)
  =20 (must:   99.0% qualifies) possible alternative.
 * version length =15 (should: 95.3% qualifies)
   - aptitude field length default can be 15 as BTS #624542 for 80 char/line
   - 10 is too short since only 83.8% qualifies.

I understand some may feel general recommendation to be in Developer's
reference in general as:

5.11.2. NMUs and debian/changelog
 http://www.debian.org/doc/manuals/developers-reference/pkgs.html#nmu-changelog
 This only talk about NMU versioning.

6.3. Best practices for debian/changelog
 
http://www.debian.org/doc/manuals/developers-reference/best-pkging-practices.html#bpp-debian-changelog
 
These are a bit more guidance than limiting version number for what we
can use.

 If we have a version number length restriction, or an overall filename
 length restriction, we should just say that, and point out that using
 hashes may make it hard to meet the restriction.

If we do this, we also need to move 3.2.1 to developers-reference.

Osamu


-- 
To UNSUBSCRIBE, email to debian-policy-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Archive: http://lists.debian.org/20110501003325.ga3...@debian.org

Bug#175064: DocBook XML conversion is read with this script

[Osamu Aoki]

Hi,

On Mon, Apr 25, 2011 at 05:25:31AM -0500, Jonathan Nieder wrote:
 Hi Osamu,
 
 Osamu Aoki wrote:
 
  By extracting attached file into source and running make, it will do
  the magic of converting to DocBok XML and then to PDF etc.
  (Need the sid version of the latest debiandoc-sgml)
 
 Very neat.  I also had to install dblatex.  I like the separation
 between automated conversion and patches to fix it up.  Some quick
 reactions:
 
 . The generated HTML refers to some missing files like
   images/prev.gif.  I assume make publish would have taken care of
   that; maybe it would be possible for a similar target to take care
   of putting a symlink or copy of the images/ dir in the source tree
   for easy previewing.

I was lazy to copy that kind of script to the makefile.  You can find it
in maint-guide subversion.  This bug report was a reminder and promting
for me to cordinate this conversion with people in charge of publishing
policy.  This is to show this conversion is possible with minimal
transtion work.
 
 . The lack of indentation in the source is nice.  Less fussy.

That is not my intention.  XML makes no distinction.  I think it may be
good idea to run some kind of lint program on XML source.

 . That said, if there were a way to preserve the whitespace of the
   original and just substitute tags (so diff-ing between the before
   and after would be possible), that would be even better.  I
   understand that's probably impossible.  I fell back to using git
   diff --no-index --word-diff=color to find meaningful differences.

If you want to do this, conversion needs to be done differently with
much more manual works.

 . Sometimes the spacing around closing tags looks unidiomatic, as in
 
   ... The detailed
   procedure for gracefully orphaning a package can be found in the Debian
   Developer's Reference (see xref linkend=related/ ).  /para 
 /footnote

I noticed this while working on maint-guide conversion.  Bug filed.

   The extra space carries over to the rendered HTML, too.  Is that
   intentional?

No.

 . Quotation marks were lost, for example in “Originally called Debian
   GNU/Linux Policy Manual, ...” at the start of the policy manual.

I was wondering on the same problem on maint-guide conversion.  Bug
filed.

 . Aside from the quotation marks and spaces, I couldn't find any
   artifacts.  Seems like a good conversion.

I am busy fixing maint-guide now.   Please let me know how I get changes
commited.  Access to git branch will be nice.

Osamu
 
 Thanks much; nicely done.
 Jonathan



-- 
To UNSUBSCRIBE, email to debian-policy-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Archive: http://lists.debian.org/20110425141447.ga3...@debian.org

Bug#613946: policy: converted to policy.dbk

[Osamu Aoki]

Hi,

policy.sgml was successfully converted but I am not sending it over mail
yet.  It may be too big.  It can build nice PDF here.

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



-- 
To UNSUBSCRIBE, email to debian-policy-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Archive: http://lists.debian.org/20110416192643.ga20...@debian.org

Bug#613946: perl-policy: converted to perl-policy.dbk

[Osamu Aoki]

Hi,

Here is for Perl Policy.

Osamu

?xml version='1.0'?
!-- -*- DocBook -*- --
!DOCTYPE book PUBLIC -//OASIS//DTD DocBook XML V4.5//EN
http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd; [
!-- Include entity definition file by uncommenting the following --
!ENTITY % versiondata SYSTEM version.ent %versiondata;
]

book lang=en
!-- This is UTF-8 encoded. --

titleDebian Perl Policy/title

bookinfo

authorgroup
author personname Raphaël Hertzog /personname /author
author personname Brendan O'Dea /personname /author
author personname The Debian Policy mailing list  /personname 
emaildebian-policy@lists.debian.org/email /author

/authorgroup
releaseinfoversion version;/releaseinfo
pubdatedate;/pubdate


abstract
para
This document describes the packaging of Perl within the Debian distribution
and the policy requirements for packaged Perl programs and modules.
/para
/abstract

copyrightyear1999, 2001/yearholderSoftware in the Public 
Interest/holder/copyright
legalnotice
para
This manual is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later
version.
/para
para
This is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.  See the GNU General Public License for more details.
/para
para
A copy of the GNU General Public License is available as
literal/usr/share/common-licenses/GPL/literal in the Debian distribution or
on the World Wide Web at ulink url=http://www.gnu.org/copyleft/gpl.html;The
GNU Public Licence/ulink.
/para
para
You can also obtain it by writing to the Free Software Foundation, Inc., 51
Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.
/para
/legalnotice

/bookinfo


chapter id=ch1titleAbout this document/title
para
This document is distributed as the literalperl-policy/literal files in the
Debian package systemitem role=packageulink
url=http://packages.debian.org/debian-policy;debian-policy/ulink/systemitem.
It is also available from the Debian web mirrors at literalulink
url=http://www.debian.org/doc/packaging-manuals/perl-policy/;/doc/packaging-manuals/perl-policy//ulink/literal.
/para
/chapter

chapter id=perltitlePerl Packaging/title
section id=versionstitleVersions/title
para
At any given time, the package systemitem role=packageperl/systemitem
should represent the current stable upstream version of Perl revision 5 (see
xref linkend=perl6/ ).
/para
para
Only one package may contain the filename/usr/bin/perl/filename binary and
that package must either be systemitem role=packageperl/systemitem or a
dependency of that package (see xref linkend=base/ ).
/para
para
Where possible, Perl should be compiled to provide binary compatibility to at
least the last released package version to allow a grace period over which
binary module packages may be re-built against the new package (see xref
linkend=binary-modules/ ).
/para
para
The systemitem role=packageperl-base/systemitem package must provide
systemitem
role=packageperlapi-replaceableabiname/replaceable/systemitem for all
released package versions it is compatible with.  The choice of
replaceableabiname/replaceable is arbitrary, but if it differs from
literal$Config{version}/literal, it must be specified in
literal$Config{debian_abi}/literal.
/para
/section

section id=basetitleBase Package/title
para
In order to provide a minimal installation of Perl for use by applications
without requiring the whole of Perl to be installed, the systemitem
role=packageperl-base/systemitem package contains the binary and a basic
set of modules.
/para
para
As Perl has been part of the essential set for some time and is used without
dependencies by such things as package maintainer scripts, systemitem
role=packageperl-base/systemitem must be priority
emphasisrequired/emphasis and marked as emphasisessential/emphasis.
/para
para
Note that the systemitem role=packageperl-base/systemitem package is
intended only to provide for exceptional circumstances and the contents may
change.  In general, only packages which form part of the base system should
use only the facilities of systemitem role=packageperl-base/systemitem
rather than declaring a dependency on systemitem
role=packageperl/systemitem.
/para
/section

section id=pathstitleModule Path/title
para
Perl searches three different locations for modules, referred to in this
document as replaceablecore/replaceable in which modules distributed with
Perl are installed, replaceablevendor/replaceable for packaged modules and
replaceablesite/replaceable for modules installed by the local
administrator.
/para
para
The module search path (literal@INC/literal) in the Debian packages has
been ordered to include these locations in the following order:
/para
variablelist
varlistentry
termreplaceablesite/replaceable (current)/term
listitem
para

Bug#175064: DocBook XML conversion is read with this script

[Osamu Aoki]

Hi,

By extracting attached file into source and running make, it will do
the magic of converting to DocBok XML and then to PDF etc.
(Need the sid version of the latest debiandoc-sgml)

Technically, conversion is ready whenever you want to do so.

Osamu


docbook-conversion.tar.gz
Description: Binary data

Bug#613946: debian-policy: anchor issues in HTML version

[Osamu Aoki]

severity 616043 wishlist
tags 616043 wontfix
severity 613946 wishlist
thanks

Hi,

Before I start, let me remind people that it is more important to
convert all these SGML documents to DocBook XML.  So far, I am having
good success for maint-guide.  I will work on this document once I get
comfortable doing this conversion.

 http://wiki.debian.org/DocbookXmlTransition

But policy is such a high profile document, I will work on this later.

On Tue, Mar 01, 2011 at 10:24:05PM -0600, Jonathan Nieder wrote:
 user debian-pol...@packages.debian.org
 clone 613946 -1 -2
 retitle -1 debiandoc2html: link titles should not have embedded tags

What debiandoc2html should do as default is pure taste issue.
I know there have been many flip-flopping.  Its enough.
The user of debiandoc2html can disable this by using -L option.

So this is not bug for debiandoc-sgml.

Please see http://bugs.debian.org/402122 first and read on to:

 http://bugs.debian.org/402122 (current default rationale)
 http://bugs.debian.org/140677 (old history)

On this basis, I am closing this bug #616042 for debiandoc-sgml.

If bug reporter carefully read all these bug reports, this aspect of bug
#613946 is at best wishlist and debian-policy maintainer should assign
wontfix tag unless submitter gives good rationale.  I think we provide
document for most browsers with decent capability.  We do not cut down
good feature useful for most user just for lowest denominator
application.  There are some console browsers such as w3m which can
handle this OK.

 retitle -2 debiandoc2html: a name anchors should enclose heading text

Hmmm... this aspect of this bug has been so for long time.  I was
wondering on this when I took over this package.  I do not see any real
negative so this is purely aesthetic concern.  If you can cite some RFC
etc., then this is real minor bug otherwise this is wishlist bug which I
will mark as wontfix since I am not going to change this old program's
behavior any more unless it is gross problem.  Until I get clear
argument, I am marking this as wishlist/wontfix so I will not get
similar complain.

 severity -1 normal
 severity -2 minor
 reassign -1 debiandoc-sgml 1.2.20
 reassign -2 debiandoc-sgml 1.2.20
 usertags 613946 + packaging

I see you are doing BTS cleaning.  

 See http://bugs.debian.org/613946 for more details.  Thoughts?

It has been answered.

This should be fixed on Lynx side.  They show up since this does not
understand as I think. But I have not fully investigated so not ready to
reassign this to them.

Properly displaying provided feature-rich HTML is burden of clients.  I
think we should not blame generating software and created data.  That is
my thought.

Thus I think this is not really a bug of debian-policy.  At best it is
wishlist bug.  Sevrity changed to wishlist.

If bug triage people think this is not a bug of debian-policy, please
feel free to close this bug.

I should say the more useful wishlist bug is debian-policy should use
DocBook XML for source :-)

Osamu



-- 
To UNSUBSCRIBE, email to debian-policy-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Archive: http://lists.debian.org/20110304141354.ga25...@debian.org

Bug#175064: Patch for UTF-8 build

[Osamu Aoki]

tags 175064 patch
thanks

Hi,

Current build use LANG=C which should work since LaTeX is forced to use
C locale.

I think older debiandoc2* used to use character conversion to high
bit latin-1 character for copy; using latin-1 if locale is not
specified as -l option.  

Under non latin-1, it shows up in
funny character.  HEX 1A or Decimal 169 is  
 © = (C) under latin-1,7,8,9,13,14,15 and 
 Š = S with v on top under latin-2,4 .
So Josip's reply makes sense.

Also (C) encoded values are
 UTF-8: 0xC2 0xA9
So it can A9 only does not work under UTF-8

So attached patch should work to build proper UTF-8 (Instead of ASCII
only) pages.

I am not pushing this hard for squeeze since we are deep freeze but if
someone wants it, please test it and use it.

Osamu

diff --git a/Makefile b/Makefile
index 9ab6801..8767276 100644
--- a/Makefile
+++ b/Makefile
@@ -18,10 +18,10 @@ perl-policy.sgml: version.ent
 	nsgmls -wall -gues $
 
 %.html/index.html: %.sgml
-	LANG=C debiandoc2html $
+	debiandoc2html -l en.UTF-8 $
 
 %-1.html: %.sgml
-	LANG=C debiandoc2html -1 -b $*-1d $  \
+	debiandoc2html -l en.UTF-8 -1 -b $*-1d $  \
 mv $*-1d.html/index.html $*-1.html  \
 rmdir $*-1d.html
 
@@ -29,19 +29,19 @@ perl-policy.sgml: version.ent
 	tar -czf $(:/index.html=.tar.gz) $(:/index.html=)
 
 %.txt: %.sgml
-	LANG=C debiandoc2text $
+	debiandoc2text -l en.UTF-8 $
 
 %.txt.gz: %.txt
 	gzip -cf9 $  $@
 
 %.ps: %.sgml
-	LANG=C debiandoc2latexps $
+	debiandoc2latexps -l en.UTF-8 $
 
 %.ps.gz: %.ps
 	gzip -cf9 $  $@
 
 %.pdf: %.sgml
-	LANG=C debiandoc2latexpdf $
+	debiandoc2latexpdf -l en.UTF-8 $
 
 %.pdf.gz: %.pdf
 	gzip -cf9 $  $@

Bug#175064: UTF-8 and DocBook XML transtion status

[Osamu Aoki]

retitle 175064 Debian policy documents should use DocBook XML in UTF-8
thanks

Even with the current SGML source, UTF-8 transition is possible.  But we
are in deep freeze and I am reluctant to push even a simple makefile
change and iconv conversion.  The recent debiandoc-sgml package support
UTF-8 even under lenny.

If you are uploading new version for squeeze and would like to know the
diff, I may be able to make it.

But  why just UTF-8.  XML is the way :-)

I totally forgot about this bug and I was surprised to see this is still
using SGML.

I have tested with maint-guide that debiandoc2xml can be used to convert
SGML to XML with minimal manual intervention if I use the bug fix
version in git repo. (#430575: http://bugs.debian.org/430575 needs to be
fixed.)

I will be testing conversion on local branch   just FYI.

Osamu




-- 
To UNSUBSCRIBE, email to debian-policy-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Archive: http://lists.debian.org/20110108033055.ga11...@debian.org

Unidentified subject!

[Osamu Aoki]

-- 
To UNSUBSCRIBE, email to debian-policy-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Archive: http://lists.debian.org/20100617160314.ga28...@debian.org

Unidentified subject!

[Osamu Aoki]

-- 
To UNSUBSCRIBE, email to debian-policy-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Archive: http://lists.debian.org/20100617160318.ga28...@debian.org

Bug#577666: debian-policy: Section list missing: base debian-installer

[Osamu Aoki]

Hi,

On Wed, Apr 14, 2010 at 08:38:38AM +0200, Joerg Jaspert wrote:
 
  The list of all sections is defined in policy:
 
http://www.debian.org/doc/debian-policy/ch-archive.html#s-subsections
 
  As for descriptions of each of those, you could use:
http://packages.debian.org/unstable/
  But there are 2 additional entries in the second list:
base
debian-installer
 
  I think these should be included and there should be link to 
http://packages.debian.org/unstable/
 
 No. base is dead, there is no base.

I now remember you there were announcement ... 

Should I file another bug report for http://packages.debian.org/unstable/?

Funny thing is that it points only to:

vmelilo (1.5.4) [debports]
Linux kernel boot loader for m68k VME processor boards. 

This is strange.

 The officially supported list of sections from dak is:

... snip. 

Thans for the details.




-- 
To UNSUBSCRIBE, email to debian-policy-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Archive: http://lists.debian.org/20100415153452.ga5...@osamu.debian.net

Bug#577666: debian-policy: Section list missing: base debian-installer

[Osamu Aoki]

Package: debian-policy
Version: 3.8.4.0
Severity: normal

The list of all sections is defined in policy:

  http://www.debian.org/doc/debian-policy/ch-archive.html#s-subsections

As for descriptions of each of those, you could use:

  http://packages.debian.org/unstable/

But there are 2 additional entries in the second list:

  base
  debian-installer

I think these should be included and there should be link to 
  http://packages.debian.org/unstable/

Osamu

-- System Information:
Debian Release: squeeze/sid
  APT prefers unstable
  APT policy: (500, 'unstable'), (500, 'testing')
Architecture: amd64 (x86_64)

Kernel: Linux 2.6.32-3-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/bash

debian-policy depends on no packages.

debian-policy recommends no packages.

Versions of packages debian-policy suggests:
ii  doc-base  0.9.5  utilities to manage online documen

-- no debconf information



-- 
To UNSUBSCRIBE, email to debian-policy-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Archive: http://lists.debian.org/20100413133628.ga15...@osamu.debian.net

Re: Flag images - technical solution

[Osamu Aoki]

Hi,

 On 17/02/2010 19:15, Mike Hommey wrote:
  On the other hand, one application will want 16x10 icons, another one
  24x15, another one may have some effects applied on the flags to better
  fit the UI design, etc.
  
  So while applications amy be using flags already, are they really using
  the same ones, and would they benefit from having only one source for
  all flags ?

Quoting Dmitry E. Oboukhov (un...@debian.org):
 May be the size must be included into path?
 
 like
 flags/countires/package/16x10/
 flags/countires/package/24x15/

On Wed, Feb 17, 2010 at 07:28:56PM +0100, Jérémy Lal wrote:
 Maybe SVG flags would address this issue ?
 
 Also when it's not possible to choose between two flags, one could imagine
 just providing an icon with the 2 or 3-letter country code in it, and no flag.

I guess, there should be coordinated technical solution in which each
package install things like
  flags/24x15/locale-id.png
  flags/16x10/locale-id.png
  flags/scalable/locale-id.svg

For some selectable locale-id, multiple icons
  flags/24x15/locale-id.variant-0.png 
 (Nothing but 2 or 3-letter country code in it)
  flags/24x15/locale-id.variant-1.png (Flag choice #1)
  flags/24x15/locale-id.variant-2.png (Flag choice #2)

Then 
  flags/24x15/locale-id.png
is managed via alternative system to point to one of the choices above.

(I know alternative is not good idea for installer, ...)

This should make things easy to impliment icon across application
without political issues, someday if someone bothers to do this.

Osamu

PS: Taiwan's reference in the public life has been moving target.  The
new president Ma of Taiwan seems to use interesting new wordings... when
he represents him to the mainland.


--
To UNSUBSCRIBE, email to debian-policy-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Archive: http://lists.debian.org/20100222155000.ga6...@osamu.debian.net

Re: Changes in the maintenance of the Developers Reference

[Osamu Aoki]

Hi,

On Mon, Sep 21, 2009 at 09:56:37AM +0200, Lucas Nussbaum wrote:
 Following a discussion on debian-de...@l.d.o[1], the way the Developers
 Reference[2] is maintained has been changed, with the aim to make it
 more public and easier for people to contribute.
...
 Finally, we could use the help from one or two other editors. Their role
 is to direct the discussions around the patches, and integrate them into
 developers-reference. If you want to help, contact the current
 maintainers and participate in the discussions on debian-pol...@.
... 
 Lucas, for the developers-reference maintainers

Good.

Since Developers reference and policy will be updated by debian-policy@
people, and cordinated by Lucas, I have added Lucas to Admin.  (If you
start moving to other repo, we need to adjust publishing protocol.)

All existing people role has been changed to debian-doc.  If Lucas feels
needed, please add people as debian-policy role.

https://alioth.debian.org/projects/ddp/
https://alioth.debian.org/project/memberlist.php?group_id=30293

So depending on your role, we expect you to be available via one of the
mailing list.

Since having backup admin will be nice, debian-policy@ side also should
have few other admins. (Lucas please add)
https://alioth.debian.org/project/admin/index.php

(I know there are many dormant account.  After ping, I am thinking
cleaning up some write access. I wonder how other alioth project managed
its member for MIA?)

Osamu


-- 
To UNSUBSCRIBE, email to debian-policy-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org

Re: What about default-syslog [Re: new release goal default-mta?]

[Osamu Aoki]

Hi,

On Tue, May 05, 2009 at 11:52:29AM +0100, Roger Leigh wrote:
 On Tue, May 05, 2009 at 10:36:51AM +0200, Michael Biebl wrote:
  martin f krafft wrote:
   [moving debian-rele...@l.d.o to Bcc, continuing discussion in bug log]
...
 I think it is a problem extending to all virtual packages, and I would
 like to see a more general solution which is applicable to all.  It
 might be worth revisiting past discussion, for example this thread:
 
 http://lists.debian.org/debian-devel/2006/08/msg01281.html
 
 (I've CCd -devel and -policy because it's a general issue which should
 ideally be in policy)
 
 The above discussion proposed a solution like default-mta.  At the time,
 I also wrote a sample virtual-default package which generated these
 -defaults packages for all virtual packages in the archive.  At the time
 I held off actually implementing this because Anthony Towns said he was
 implementing a better method in dpkg itself.  However, I've not seen any
 more about this other than that single time, and if mta-defaults is being
 created it looks like we are still looking for a solution.

A word like default tends to create tension.  Extending existing idea
like sensible-utils package for sensible-* command wrapper seems to
be good idea. 

 It would be great if we can have a general method for specifying
 distribution-wide virtual package defaults, of which
 mail-transport-agent-default is just one.

As I read this and looking at our archive, we have:

Package sensible-mda (Priority: extra)
* Packaged by: Richard Nelson cow...@debian.org
* Sendmail source package
* On and after lenny (stable) (mail): Mail Delivery Agent wrapper
  used by dspam and sendmail
  procmail | maildrop | deliver

Package sensible-utils (Priority: required)
* Packaged by: Clint Adams sch...@debian.org
* Sensible-utils  source package
* On and after squeeze (testing) (utils): Utilities for sensible 
alternative selection
  these scripts used to be part of debianutils
  this provides sensible-{browser,editor,pager}

If a command is expected to be always on the system, integrate it into
sensible-utils seems good idea ... especially for mta and syslog if
Clint agrees.

(If a command is an optional one on the system, create package like
sensible-mda.)

Distribution choice can be expressed by the order of Depends: line.  But
installer can always override it peacefully by changing only one package.

Osamu


-- 
To UNSUBSCRIBE, email to debian-policy-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org

Re: Processed: Taking manoj's advice for how to get a practice in place

[Osamu Aoki]

reassign 486754 developers-reference
tags 486754 moreinfo
severity 486754 wishlist
thanks

Hi,

This is for http://bugs.debian.org/486754

Manoj was right to say I do not see why this should be policy, as
opposed to a best practice's thing in the dev ref. (typo fixed as s/4/'/)

He meant Developers Reference.

I personally feels this bug report does not have concrete suggestion for
improving situation.  It is not waring to user either.  It is almost
rant.  I was very much inclined to close it. Thus I tagged it moreinfo
etc. while reassigning from unrelated package of mine.  

Dan, I know you are frequent BTS reporter.  So I expect you to know
better than newbie reporter.  Please do not use bts command for this
kind of situation.  Please make sure to get full information to the
package owner.  I had to dig into bts web site.  This is not nice and
waist everyone's time.

Osamu

On Wed, Jun 18, 2008 at 03:18:07AM +, Debian Bug Tracking System wrote:
 Processing commands for [EMAIL PROTECTED]:
  reopen 486754
 Bug#486754: standardize dummy package tags
  reassign 486754 debian-reference
 Bug reassigned from package `debian-policy' to `debian-reference'.


-- 
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]

Bug#253511: reassign to developers-reference (Rejected: Bug#253511)

[Osamu Aoki]

reopen 253511
reassign 253511 developers-reference
severity  253511 wishlist
tags 253511 - wontfix
retitle 253511 provide guideline to keep the package namespace sane
thanks

Hi,

Thanks for cleaning up BTS.

I agree with the rationale of Russ on closing this bug.

As I look back, this old bug report should have been a wishlist bug to
developers-reference since it is Best Practice issue.  What I proposed
does not fit with Policy but it is something mentioned as a guide line. 

I know this problem is addressed via WNPP process described in 5.1.
There is a link to http://ftp-master.debian.org/REJECT-FAQ.html:
There, 2nd reason for rejection is listed as:
 * trying to keep the package namespace sane,
But it goes only to define in the later table as:
 Package name   Use the right package names. A lib should start with
 lib, a perl module with lib and end with -perl, etc

The contents in REJECT-FAQ is reasonable since it is Policy like
strong statement.  But for the sake of better usability, we should
recommend some guideline in developers-reference.  I mean something
along what I proposed before for Policy 3.1 is needed to be added to
developers-reference 5.1.

Osamu

On Fri, Jun 06, 2008 at 10:49:06PM +, Debian Bug Tracking System wrote:
 #253511: [PROPOSAL] clarify package must have a name that's unique ...
 It has been closed by Russ Allbery [EMAIL PROTECTED].
 -- 
 253511: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=253511

 From: Russ Allbery [EMAIL PROTECTED]
 Subject: Rejected: Bug#253511: clarify package must have a name that's 
 unique ...
 To: debian-policy@lists.debian.org
 Cc: [EMAIL PROTECTED]
 Date: Fri, 06 Jun 2008 11:52:17 -0700
 
 This is a proposal to add some standards to Policy for how packages should
 be named to avoid short package names or names that are more common than
 the package deserves (camera, terminal, etc.).
 
 The proposal was discussed briefly in 2004 and then the discussion died
 without proposed wording or apparent consensus.
 
 This topic is still discussed from time to time on debian-devel, but it's
 difficult to write a Policy provision that incorporates the various
 common-sense guidelines that go into good package names.  My belief is
 that public review on debian-devel with the possible intervention of
 ftpmaster where necessary is preferrable to trying to codify rules for
 package naming in Policy.
 
 For that reason, plus lack of consensus, I am rejecting this proposal.
 This is a soft rejection, meaning that if someone feels strongly about
 this proposal and wants to step forward to champion it again, I'd be
 willing to reopen the bug.
 
 -- 
 Russ Allbery ([EMAIL PROTECTED])   http://www.eyrie.org/~eagle/
 

 From: Osamu Aoki [EMAIL PROTECTED]
 Subject: [PROPOSAL] clarify package must have a name that's unique ...
 To: Debian Bug Tracking System [EMAIL PROTECTED]
 Date: Wed, 9 Jun 2004 22:46:30 +0200
 
 Package: debian-policy
 Version: 3.6.1.0
 Severity: normal
 
 Currently policy states:
 
 |3.1. The package name
 |-
 |
 | Every package must have a name that's unique within the Debian
 | archive.
 |
 | The package name is included in the control field `Package', the
 | format of which is described in Section 5.6.6, ``Package''.  The
 | package name is also included as a part of the file name of the `.deb'
 | file.
 
 Here there is no restriction for the package name being *sane*.
 
 On the other hand, 3.2. The version of a package has
 ...
 | If an upstream package has problematic version numbers they should be
 | converted to a sane form for use in the `Version' field.
  
 
 This gives a good ground for not choosing bad version naming.
 
 Most of us think that keeping *unique* name requires the choice of
 package name to be *sane* :)  (Yes, I know a gnustep application
 packager disagreed.)
 
 We need to clarify the position of Debian on 3.1.
 
 Let me propose:
 
 |3.1. The package name
 |-
 |
 | Every package must have a name that's unique within the Debian
 | archive.
 |
 | The package name is included in the control field `Package', the
 | format of which is described in Section 5.6.6, ``Package''.  The
 | package name is also included as a part of the file name of the `.deb'
 | file.
 |
 + If an upstream package has problematic name they should be converted
 + to a sane form for use in the `Package' field.
 +
 +3.1.1. Package name guidelines
 +--
 + Use of common sense to avoid name space pollution of package names
 + are encouraged.  The package name should be longer than 4
 + characters and should not use generic words. Use of prefix to
 + identify name a group of softwares which are applicable only for 
 + the subset of the Debian environment is encouraged.  Some
 + traditional popular programs may be exempted from these restriction.
 
 I welcome better

Bug#473439: Debian Reference is not policy or Developer reference

[Osamu Aoki]

reassign 473439 debian-policy
thanks

Hi,

http://bugs.debian.org/473439

After reading the original bug report, tis is not Debian Reference but
Debian Policy.  So I am reassigning this.

As for Debian Reference, English version os about to be replaced with 
 
http://people.debian.org/~osamu/pub/getwiki/html/ch03.en.html#debianarchivebasics

Please file another bug on Debian Reference.  I think I did my best to
address situation with my opionion how they should be called.

I even clarify my rationale:
http://people.debian.org/~osamu/pub/getwiki/html/ch03.en.html#authenticityofthepackage

Cheers,

Osamu




-- 
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]

Bug#473439: debian-policy: Debian Policy inconsistent with Developer's Reference

[Osamu Aoki]

On Sun, Mar 30, 2008 at 12:07:38PM -0700, Russ Allbery wrote:
 Adam D. Barratt [EMAIL PROTECTED] writes:
  On Sun, 2008-03-30 at 11:30 -0700, Russ Allbery wrote: 
  Meike Reichle [EMAIL PROTECTED] writes:
 
  When doing my NM I noticed an inconsistency between the Debian Policy
  and the Developer's Reference concerning the use of the terms section
  and category.
  [...]
  The control field for specifying admin, net, utils, etc. is Section, so
  I think Policy wins here and main, contrib, and non-free should be called
  categories.

In 2.4 Sections:
 * section if the package is in the main category,
 * segment/section if the package is in the contrib or non-free distribution 
areas.

Here 
 main is category
 contrib or non-free are distribution areas but their name can be used as 
segment.

  For what it's worth, and possibly to add more confusion, dak uses the
  term component in this case.

Release file downloaded to user system calls them component too.
 
 Also, I guess my first reaction isn't as conclusive as I'd like, since
 Section, the control field, is actually used for both.
 
 I sort of like component better than category.  I wonder if we should
 change both documents.  Although I think Policy is fairly uniform and
 consistent on using category, and other software, like Lintian, follows
 the current terminology of Policy.

I also realized confsing situation in terminology. 

The terminology used in Social contract is another point too.
component seem to indicate package level component in distribution.
main/contrib/non-free things are called as area.

I now use component for main/contrib/non-free following the Release
file notation for next rewrite.

Then I mention as:
In the stricter Debian archive terminology, the word section is
specifically used for the categorization of packages by the application
area.  (Although, the word main section may sometimes be used to
describe the Debian archive section which provides the main suite.)

More on:
http://people.debian.org/~osamu/pub/getwiki/html/ch03.en.html#debianarchivebasics

You can edit it (once good text is agreed.)
http://wiki.debian.org/DebianReference/Package

Anyway, consistency with Developer's reference is non-issue for Policy
since Policy is higher level document.  But Policy must be consistent
with words usage by the key Debian infrastructure (DAK) to be consistent.

Once Policy is consistent with DAK, Developer Reference and others can
follow.  

Current Developer reference has some parts coming from packaging manual.
That may be another source of inconsistency.

Osamu




-- 
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]

Re: Bug#334821: Home page: in debian/control should be Homepage:

[Osamu Aoki]

On Sat, Oct 22, 2005 at 11:34:28PM -0400, Jean-Marc Ranger wrote:
 Sorry to bring even more oil to this already quite large fire.

Thanks for your good research :-)

I just updated developer-reference follwing your private communication.

As you pointed out to me, the debian-policy odiscussion below is quite
interesting.

  http://lists.debian.org/debian-policy/2005/10/msg00042.html

Jean-Marc did good research to find a package that matches the
recommendation which: 
- has both spaces
- doesn't spell it home page
- has the : following homepage
- doesn't surround the address with 
- doesn't use the Author pseudo-field that was also proposed in Dec.
  2002 but not kept in developers-reference.

This is wml package. :-)


-- 
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]

Re: Home page: in debian/control should be Homepage:

[Osamu Aoki]

reassign 334821 developers-reference
tags 334821 fixed-upstream
thanks

Hi,

Peter, I am not in debating mode with you. 

(I usually follow these official best practice descriptions when I
noticed even if they are not convincing as long as it does not break
things.  But that is me.)

I will give you some background info of this best practice below for
your reference.

When I saw this bug report to developer-reference, I thought an simple
reminder with the reason referenced to the developer-reference will
convince you and fix this situation.  I was wrong ...

Everyone, I CC debian-policy where this recommendation was decided.  I
am changing CVS (common.ent) so the next developer's reference will be
consistent and Peter can have his own way.

- !ENTITY url-eg-desc-upstream-info 
http://packages-host;/unstable/text/docbook-dsssl.html;
+ !ENTITY url-eg-desc-upstream-info 
http://packages-host;/unstable/text/docbook.html;

On Sat, Oct 22, 2005 at 05:28:17PM +0200, Peter Eisentraut wrote:
 Am Samstag, 22. Oktober 2005 03:03 schrieb Osamu Aoki:
  Did you decided by yourself that the correct English spelling words with
  colon should be used instead of developer-reference defined pseudo
  header Homepage: on your package?
 
 I know of no policy document or other convincing technical reason that this 
 needs to be spelled one way or the other.  The policy says that the 
 description should describe the package to the user, so natural language 
 spelling rules apply.  I also use Web site: http://foo; or Home pages: 
 http:// and http://bar; in other packages, and no one ever saw problems with 
 that.

This is recommendation by the developer's reference.  This document is
meant for the best practice guide. This is not policy although its
updates are usually consulted to debian-policy mailing list.

 I am of course aware of the section in the Developer's Reference (although I 
 never fully realized that the docbook-dsssl package was linked as the 
 example) but I figured that the point of the section was to show that noting 
 the web site would make it clickable in the package pages, not to advocate 
 some sort of pseudoheader.  Right now I can't even think of a real 
 application for programmatically knowing a package's upstream web sites.

Well, fortunately Debian web site script seems to be smart enough to cope with
people like you :-)  It creates http-link properly.

 Reading this closely now I also notice that only a minority of packages seems 
 to follow the advice of putting two spaces before Homepage, the rationale 
 behind which is also unclear to me.

Debian is functioning as an open process.  I personally do not care how
this was decided but this can be found.  The developer's reference is
available in CVS.  It's CVS is viewable by web too. 

 http://cvs.debian.org/?cvsroot=debian-doc

 
http://cvs.debian.org/ddp/manuals.sgml/developers-reference/developers-reference.sgml?cvsroot=debian-doc

As you click through annotate and read sections defining this, it is
created around 1.150-1.152 which are in December 2002.  Reading comments
of these commits points us to check debian-policy mailing list archive
of December 2002. You can find aph being one proposed this and
discussion there is the reason.  Many there were quite happy with the
way it is spelled at least.  If you think this is bad recommendation,
please discuss there.

You know aph (Adam) is the one who packaged docbook-dsssl before you
started to maintain this :-) Thai is why this package was chosen as the
example  of this yet-not-so-popular best practice.

 To summarize, it's doubtful that this matters one way or the other.

Then why insists?

Osamu






-- 
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]

how to search by Message-ID

[Osamu Aoki]

Hi,

On Fri, Nov 14, 2003 at 01:54:51PM +, Julian Gilbey wrote:
 How?  I haven't figured out how to search by Message-ID.

For Message-ID in any debian lists, use:
 http://groups.google.com/

Enter: 
 site:lists.debian.org Message-ID

This works for me :-)

Osamu

Bug#184368: sematic error, 2.3.1 The package name

[Osamu Aoki]

On Tue, Mar 11, 2003 at 03:57:07PM -0600, Drew Scott Daniels wrote:
 Package: debian-policy
 
 Section 2.3.1 says:
 Package names must consist of lower case letters (a-z), digits (0-9),
 plus (+) and minus (-) signs, and periods (.).
 
 It should say something like:
 Package names must not consist of anything other than lower case letters
 (a-z), digits (0-9), plus (+) and minus (-) signs, and periods (.).
 
 because it is not desirable, and not the current convention to make
 packages contain all of the items in the list. eg why force apt to have
 digits, plus and minus signs and periods. It would have to have a name
 like apt00+-.. to be valid.

Please do not push pedantic argument too much :-)

Double negative expressions are error prone and difficult to understand
for non-native speakers.  I think it is fine as is since the original
text uses consist of instead of contain.

BTW, I have never seen any package name starting any of +, -, or
., nor I have seen any package name with repeated ..  I guess common
sense rules.

-- 
Osamu Aoki [EMAIL PROTECTED]   Cupertino CA USA, GPG-key: A8061F32

pgp in virtual-package-names-list

[Osamu Aoki]

As I see woody/sarge/sid archive, I see only one version of PGP.

Version: 2.6.3a-9
Replaces: pgp-i, pgp-us

Do we still need pgp entry in virtual-package-names-list.txt.gz

pgp A version of PGP (International or US)

Was this fixed in CVS?

-- 
~\^o^/~~~ ~\^.^/~~~ ~\^*^/~~~ ~\^_^/~~~ ~\^+^/~~~ ~\^:^/~~~ ~\^v^/~~~ +
Osamu Aoki [EMAIL PROTECTED]   Cupertino CA USA, GPG-key: A8061F32
 .''`.  Debian Reference: post-installation user's guide for non-developers
 : :' : http://qref.sf.net and http://people.debian.org/~osamu
 `. `'  Our Priorities are Our Users and Free Software --- Social Contract

Bug#182792: debian-policy: Typo-fix and reformat virtual-package-names-list.txt

[Osamu Aoki]

Package: debian-policy
Version: 3.5.8.0
Severity: normal
Tags: patch

In virtual-package-names-list.txt, some package names had colon (2),
comma (1) or period (1) after them.  Also update date to 2003 since last
change is 2003.  I guess these are typos.  Hence normal bug.

Also it was not so easy to extract data by script.  I Inserted space
before package name. With grep '^ [a-zA-Z0-9]', it makes it easy to
feed this into script to extract virtual package names.

If you do not like me adding spaces, 

(Yes, I am playing with aptitude database and I like to have easily
updatable information.)

--- virtual-package-names-list.txt.old  2002-11-14 17:45:32.0 -0800
+++ virtual-package-names-list.txt  2003-02-27 15:27:55.0 -0800
@@ -1,7 +1,7 @@
 
   AUTHORITATIVE LIST OF VIRTUAL PACKAGE NAMES
 
-February 2001
+February 2003
 
 
 Below is an authoritative list of virtual package names currently
@@ -49,91 +49,93 @@
 
 X Window System
 ---
-x-terminal-emulator any X client which emulates a terminal with a
-terminfo description in the ncurses-base package
-x-window-managerany X client which provides window management
-services
-xserver any X server that (directly or indirectly) manages
-physical input and display hardware
+ x-terminal-emulator any X client which emulates a terminal with a
+ terminfo description in the ncurses-base package
+ x-window-managerany X client which provides window management
+ services
+ xserver any X server that (directly or indirectly) manages
+ physical input and display hardware
 
 Miscellaneous
 -
 [Those marked with a (*) are handled using the alternatives mechanism;
 others may do so as well.]
-awk Anything providing suitable /usr/bin/{awk,nawk} (*)
-c-compiler  Anything providing a C compiler
-c-shell Anything providing a suitable /bin/csh (*)
-debconf-2.0 Any package that provides the debconf protocol
-dhcp-client Any package providing a DHCP client 
-dotfile-module  Anything that provides a module for the
-Dotfile Generator
-dict-client Any package providing clients for the Dictionary Server
-dict-server Any package providing the Dictionary Server
-emacsen Anything providing the GNU emacs or a
-compatible editor
-foomatic-data   Any package providing PPD printer description files
-fortran77-compiler  Anything providing a Fortran77 compiler
-ftp-server  Any ftp server
-httpd   Any HTTP server
-ident-serverAnything providing an identd daemon
-info-browserSomething that can browse GNU Info files
-aspell-dictionary   Anything providing a dictionary for the aspell system
-ispell-dictionary   Anything providing a dictionary for the ispell system
-kernel-headers  Kernel header files (linux/*.h, asm/*.h)
-kernel-imageKernel image (vmlinuz, System.map, modules)
-kernel-source   Kernel source code
-linux-kernel-log-daemon A daemon to facilitate logging for the Linux kernel
-lambdamoo-core  A lambdamoo-compatible database package  
-lambdamoo-serverAnything running a moo using a lambdamoo-core
-libc-devAnything that provides header and object files
-of `libc'
-man-browser Anything that can read man pages
-radius-server   Any package that provides a RADIUS server for acct/auth
-rsh-client  Any package that provides an rsh client
-rsh-server  Any package that provides an rsh server
-system-log-daemon   A daemon that provides a logging facility for
-other applications
-tclsh   Anything that provides /usr/bin/tclsh (*)
-telnet-client   Any package that provides a telnet client
-telnet-server   Any package that provides a telnet server
-time-daemon Anything that servers as a time daemon
-ups-monitor Anything that is capable of controlling an UPS
-wishAnything that provides /usr/bin/wish (*)
-wordlistAnything that provides /usr/share/dict/words (*)
-www-browser Something that can browse html files
+ awk Anything providing suitable /usr/bin/{awk,nawk} (*)
+ c-compiler  Anything providing a C compiler
+ c-shell Anything providing a suitable /bin/csh (*)
+ debconf-2.0 Any package that provides the debconf protocol
+ dhcp-client Any package providing a DHCP client 
+ dotfile-module  Anything 

Re: Bug#182792: debian-policy: Typo-fix and reformat virtual-package-names-list.txt

[Osamu Aoki]

...
 feed this into script to extract virtual package names.
 
 If you do not like me adding spaces, 

OOps, missing.

If you do not like me adding spaces, just fix 4 typos and date.

-- 
~\^o^/~~~ ~\^.^/~~~ ~\^*^/~~~ ~\^_^/~~~ ~\^+^/~~~ ~\^:^/~~~ ~\^v^/~~~ +
Osamu Aoki [EMAIL PROTECTED]   Cupertino CA USA, GPG-key: A8061F32
 .''`.  Debian Reference: post-installation user's guide for non-developers
 : :' : http://qref.sf.net and http://people.debian.org/~osamu
 `. `'  Our Priorities are Our Users and Free Software --- Social Contract

Bug#175064: Debian policy documents should be UTF-8 encoded

[Osamu Aoki]

Hi,

disclaimerI prefer to migrate to UTF-8./disclaimer 

But simply changing source file to UTF-8 has some issues which you may
want to consider in advance. (debian-policy being English only manual,
risks are small.)

I think it may be best if this encoding changes are done at the same
time when this documentation is moved to docbook-xml format.  A
functional conversion script already exists.  See below for the detail.

On Thu, Jan 02, 2003 at 05:20:26PM -0500, Colin Walters wrote:
 On Thu, 2003-01-02 at 16:28, Josip Rodin wrote:
 
  I'm not seeing that with the copy of policy.txt.gz which I generated myself.
  Looks like debiandoc2text on Manoj's system used a different, Latin1 locale
  and replaced ?? for copy; on my Latin2 system it did no such (foolish) 
  thing.
  For the record, ?? is a large latin letter S with a hacek/caron. :)
  
  We should probably restrict the build process with LANG=C or something like
  that.
 
 Right.  I think it should be sufficient to just add LANG=C before the
 debiandoc2X invocations.

Debiandoc2X basically assumes legacy codings in the source file as it
designed now.  Just add LANG=C before the debiandoc2X invocations does
not do much since it is required to be LANG=C and the script sets locale
by command line option with -l and invoke back-end processing commands
with that local as I understand.  (I may be wrong here.)

As I understand, you can use UTF-8 source file for creating plain text
and html files in UTF-8 (I guess html generation needs slightly modified
to indicate generated codes are UTF-8 in its header).  But It will break
PS and PDF generation pretty badly.  (I have been there with my Italian
translator committing UTF-8 file to the document I manage.)

I think Ardo used Latin-1 as code system for back-end at this moment.
Changing this will break many documentation building processes.

In debian-doc project, we have created debiandoc-sgml to docbook-xml
converter.  It is now very usable shape.  If someone makes nice build
script and environment for docbook-xml and spend sometime to hand tune
converted files (including converting it to UTF-8), it should be
smoother transition.  After all SGML used to use legacy encoding system
as the default for the source files while XML's default source encoding
is UTF-8.

URL for conversion script (by Phillipe):
 http://cvs.debian.org/ddp/utils/debiandoc-to-docbook/?cvsroot=debian-doc

Just my thoughts.

Osamu
-- 
~\^o^/~~~ ~\^.^/~~~ ~\^*^/~~~ ~\^_^/~~~ ~\^+^/~~~ ~\^:^/~~~ ~\^v^/~~~ +
Osamu Aoki [EMAIL PROTECTED]   Cupertino CA USA, GPG-key: A8061F32
 .''`.  Debian Reference: post-installation user's guide for non-developers
 : :' : http://qref.sf.net and http://people.debian.org/~osamu
 `. `'  Our Priorities are Our Users and Free Software --- Social Contract

Bug#175064: Debian policy documents should be UTF-8 encoded

[Osamu Aoki]

On Tue, Jan 07, 2003 at 11:42:30PM +0100, Josip Rodin wrote:
 On Tue, Jan 07, 2003 at 10:49:03AM -0800, Osamu Aoki wrote:
  I think it may be best if this encoding changes are done at the same
  time when this documentation is moved to docbook-xml format.
 
 I'm entirely not convinced that we should go beyond ASCII because a program
 can't be taught to convert copy; into (C). It's just that, nothing else.

I think we may be discussing slightly different things.  I do not
understand what you ment by the above message.  They are taught to do
so, I think.

Current debiasndoc-sgml creates copyright section starting with

  HTML:   Latain-1 code for copy;  (1 character)
  PDF:Latain-1 code for copy;  (1 character)
  Plain text: ASCII 3 characters (C)

That was today's build of my documment results.  The source are like:

  copyrightsummary
  Copyright copy; 2001ndash;2002 by Osamu Aoki lt;osamu;gt;.
  /copyrightsummary

The plain text does not go beyond ASCII.  Neither UTF-8 nor ISO-8859-1.

Osamu
-- 
~\^o^/~~~ ~\^.^/~~~ ~\^*^/~~~ ~\^_^/~~~ ~\^+^/~~~ ~\^:^/~~~ ~\^v^/~~~ +
Osamu Aoki [EMAIL PROTECTED]   Cupertino CA USA, GPG-key: A8061F32
 .''`.  Debian Reference: post-installation user's guide for non-developers
 : :' : http://qref.sf.net and http://people.debian.org/~osamu
 `. `'  Our Priorities are Our Users and Free Software --- Social Contract

Bug#175064: Debian policy documents should be UTF-8 encoded

[Osamu Aoki]

On Wed, Jan 08, 2003 at 12:55:01AM +0100, Josip Rodin wrote:
  The plain text does not go beyond ASCII.  Neither UTF-8 nor ISO-8859-1.
 
 % zgrep ?? /usr/share/doc/debian-policy/policy.txt.gz
  Copyright ?? 1996,1997,1998 Ian Jackson and Christian Schwarz.
 
 How do you explain that? Honest question :)

Honestly, I can not explain.  I see copy; in the source and single
character copyright mark in installed text too.  Maintainer may have had
different conversion catalog or Ardo changed conversion table since then.

I had testing environment and I just upgrading to unstable for
debiandoc-sgml.  Still I get (C) even for policy source.  (Well, current
policy was FTBFS in my system when I did a very quick check to rebuild.)

I have not checked with chroot condition for woody or potato.  But this
situation seems really build environment issue.

(ISO-8859-1 is my mailer) txt.gz
debian-policy_3.1.1.1.deb (C)
debian-policy_3.5.6.1_all.deb  ©
debian-policy_3.5.8.0_all.deb  ©15 Nov 2002

Osamu

-- 
~\^o^/~~~ ~\^.^/~~~ ~\^*^/~~~ ~\^_^/~~~ ~\^+^/~~~ ~\^:^/~~~ ~\^v^/~~~ +
Osamu Aoki [EMAIL PROTECTED]   Cupertino CA USA, GPG-key: A8061F32
 .''`.  Debian Reference: post-installation user's guide for non-developers
 : :' : http://qref.sf.net and http://people.debian.org/~osamu
 `. `'  Our Priorities are Our Users and Free Software --- Social Contract

Re: should XML/SGML documentation ship with sources

[Osamu Aoki]

On Sun, Dec 08, 2002 at 10:44:18PM -0500, Colin Walters wrote:
 On Sun, 2002-12-08 at 17:32, Adam DiCarlo wrote:
  I have a question for further discussion, which I'm unsure about.  May
  or may not be a policy issue.
  
  Is it a good practice for SGML or XML documentation to ship with
  source?
  
  Pros:
   - providing source lets contributors make patches more easily
 
- It would in theory let software like doc-base dynamically generate
 the documentation formats the user desires after installation.

Isn't it against the spirit of binary distribution?

deb-file should contain
 Plain text (singe file for grep)
 Multi-file HTML
 PS
 PDF
 
while source shall contain SGML/XML only with proper build depends
provided.

Osamu
-- 
~\^o^/~~~ ~\^.^/~~~ ~\^*^/~~~ ~\^_^/~~~ ~\^+^/~~~ ~\^:^/~~~ ~\^v^/~~~ +
Osamu Aoki [EMAIL PROTECTED]   Cupertino CA USA, GPG-key: A8061F32
 .''`.  Debian Reference: post-installation user's guide for non-developers
 : :' : http://qref.sf.net and http://people.debian.org/~osamu
 `. `'  Our Priorities are Our Users and Free Software --- Social Contract

Re: should XML/SGML documentation ship with sources

[Osamu Aoki]

On Sun, Dec 08, 2002 at 04:32:10PM -0600, Adam DiCarlo wrote:
 
 I have a question for further discussion, which I'm unsure about.  May
 or may not be a policy issue.
 
 Is it a good practice for SGML or XML documentation to ship with
 source?
 
 Pros:
  - providing source lets contributors make patches more easily

How much more easy?  

Just make README.Debian mention apt-get source src-package-name

 Cons: 
  - wastes disk space
Yes
  - why bother, just get the source pkg

Or why contaminate binary distribution content :)

I do not like the duplication of the content.

Osamu
-- 
~\^o^/~~~ ~\^.^/~~~ ~\^*^/~~~ ~\^_^/~~~ ~\^+^/~~~ ~\^:^/~~~ ~\^v^/~~~ +
Osamu Aoki [EMAIL PROTECTED]   Cupertino CA USA, GPG-key: A8061F32
 .''`.  Debian Reference: post-installation user's guide for non-developers
 : :' : http://qref.sf.net and http://people.debian.org/~osamu
 `. `'  Our Priorities are Our Users and Free Software --- Social Contract

Re: should XML/SGML documentation ship with sources

[Osamu Aoki]

On Wed, Dec 11, 2002 at 05:58:17PM -0600, Adam DiCarlo wrote:
 
 The consensus we arrived at on debian-doc list (with the exception of
 Colin Walters) was that XML/SGML source is in fact source and
 shouldn't be there bloating binary pkgs.  

Thanks for summarizing. I should have responded to debian-policy (I
bounced my message to here for archival purpose.) 

 Just FYI.  Not that I'm proposing this as a policy item, although it
 might become DDP policy, who knows.

Actually, that is a part of what me and Javi are going after while we are
making draft for the DDP-policy now.  

All DDP-document shall supply plain text, multi-file html, PS, and PDF
but no SGML source. is in tentative DDP-policy.

This DDP-policy is nowhere near public release but it is available at
http://www.debian.org/doc/manuals/ddp-policy/ddp-policy.en.html for
people concered to make comments.  All Debian developers can access its
source in DDP CVS and are welcomed to add alternatives views there.  Our
plan is, once all options are laid down, we want to come to the consensus
within debian-doc and propose it to debian-policy.  This DDP-policy
things happened when Adam was quiet on debian-doc.  

Because of the nature of documetation, ddp-policy will likely be more of
the Best Practice guide with many shoulds, I think.

-- 
~\^o^/~~~ ~\^.^/~~~ ~\^*^/~~~ ~\^_^/~~~ ~\^+^/~~~ ~\^:^/~~~ ~\^v^/~~~ +
Osamu Aoki [EMAIL PROTECTED]   Cupertino CA USA, GPG-key: A8061F32
 .''`.  Debian Reference: post-installation user's guide for non-developers
 : :' : http://qref.sf.net and http://people.debian.org/~osamu
 `. `'  Our Priorities are Our Users and Free Software --- Social Contract

Bug#172022: FWD: Re: description writing guide

[Osamu Aoki]

Hi,

On Sun, Dec 08, 2002 at 09:06:50PM +0100, Josip Rodin wrote:
...
 +sect1 id=synopsisheadingThe single line synopsis/heading
  
 p
   The single line synopsis should be kept brief - certainly
 @@ -2397,6 +2421,10 @@
   informative as you can.
 /p

I think short or single line is still vague.  
(I heard that Josip's NM guide talks about something like 60 chars while
somewhere in developer-reference talks about 80 chars)

How about specify exact length of this synopsis (with *should*).

  (synopsis content length)  77 characters - (package name length)

(This is my speculation for the limit of dselect display on 80char
screen.)

I should note that there are many packages with longer synopsis which
overrun dselect display on VT-100 screen.

Sorry to be weak in the fact side.

Osamu
-- 
~\^o^/~~~ ~\^.^/~~~ ~\^*^/~~~ ~\^_^/~~~ ~\^+^/~~~ ~\^:^/~~~ ~\^v^/~~~ +
Osamu Aoki [EMAIL PROTECTED]   Cupertino CA USA, GPG-key: A8061F32
 .''`.  Debian Reference: post-installation user's guide for non-developers
 : :' : http://qref.sf.net and http://people.debian.org/~osamu
 `. `'  Our Priorities are Our Users and Free Software --- Social Contract

Bug#39830: [AMENDMENT]: get rid of undocumented(7) symlinks

[Osamu Aoki]

 --- policy.sgml.orig  2002-11-12 12:50:40.0 +
 +++ policy.sgml   2002-11-12 12:51:30.0 +
 +   There should be a manual page at least for every program.  If
 +   no manual page is available, this is considered as a bug and
 +   should be reported to the Debian Bug Tracking System (the

Specify maximum bug level here please if it is not a problem. 
Makes it easy for people to agree in case of dispute.  
Certainly not RC bug :-)

 +   maintainer of the package is allowed to write this bug report
 +   himself, too).  Do not close the bug report until a proper
 +   manpage is available.footnote

I guess missing manual will be handled by a patch to the man program but
above still applies.

-- 
~\^o^/~~~ ~\^.^/~~~ ~\^*^/~~~ ~\^_^/~~~ ~\^+^/~~~ ~\^:^/~~~ ~\^v^/~~~ +
Osamu Aoki [EMAIL PROTECTED]   Cupertino CA USA, GPG-key: A8061F32
 .''`.  Debian Reference: post-installation user's guide for non-developers
 : :' : http://qref.sf.net and http://people.debian.org/~osamu
 `. `'  Our Priorities are Our Users and Free Software --- Social Contract

Bug#146703: debian-policy needs to be made by the latest debiandoc-sgml

[Osamu Aoki]

Package: debian-policy
Version: 3.5.6.1
Severity: wishlist

Action requested:
1. recreate updated package in latest woody environment. (desirable)
2. if time permits, add ps and pdf files to the package (wishlist)

Problems:
If HTML pages are seen by links or lynx, it will look bad currently.
This problem comes from debiandoc-sgml and fixed in latest testing
version 1.1.67.

Please recreate new packages in new environment.  --- (1)

Also I see many tex and latex files in source but no ps nor pdf.  With
latest debiandoc-sgml, ps and pdf can be build nicely without hack.  So
you may consider including them.  Just debiandoc2latexpdf and
debiandoc2latexps will do it :)  

Just minor patches to debian/rules. -- (2)

I am speaking from following current install situation:
Desired=Unknown/Install/Remove/Purge/Hold
| Status=Not/Installed/Config-files/Unpacked/Failed-config/Half-installed
|/ Err?=(none)/Hold/Reinst-required/X=both-problems (Status,Err: uppercase=bad)
||/ Name   VersionDescription
+++-==-==-
hi  debiandoc-sgml 1.1.67 DebianDoc SGML DTD and formatting tools
ii  debian-policy  3.5.6.1Debian Policy Manual and related documents
-- 
+++
+  Osamu Aoki [EMAIL PROTECTED] @ Cupertino, CA USA +



pgphgSXqqXnwU.pgp
Description: PGP signature