Bug#600883: debhelper: Please improve manual page typography
Hello, I commited update french translation. The updates are based exclusively on the added typography of David Prevot, but I think what there is more updates to do in originals man pages for completly conform to Debian rules. I'll write to David, (but in french it's more easy for me) for this. Regards Valéry Perrin Le 21/10/2010 00:31, Joey Hess a écrit : > David Prévot wrote: > >> While reviewing manual pages translation, I noticed that some parts >> of the manual pages doesn't follow guidelines conventions available >> in man(1), and could be improved in order to make it easier to pick >> information in them. >> >> The attached patch is a review taking care of these conventions, only >> in debhelper(7), but I'm willing to provide you a review of the other >> manual pages if it's fine with you to apply them (and if some of them >> are not justified, please let me know so I won't propose them for the >> other pages). >> > I find getting that exactly right to be tedious and hard, so if you > can supply patches, you're a better editor than I. :) > > I will apply such patches, just please let me know if the entire patch > is changes to markup, so I don't need to review it for content.. > > signature.asc Description: OpenPGP digital signature
Bug#600883: debhelper: Please improve manual page typography
I'm already on it. Hope to finish it in the following days. Regards, -- Omar Campagne Polaino -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org
Bug#600883: debhelper: Please improve manual page typography
Hello, Yes, we've agreed with david before this manpages update. I start now and I hope upload po.fr next week. Regards Valéry Perrin (a poor translator !) Le 05/11/2010 23:32, David Prévot a écrit : > Hi, > > Le 05/11/2010 17:33, Joey Hess a écrit : > > I do wonder about the poor translators, especially for French which was > > going to get back to 100% in this release. It would be great if the > > translations could be fixed up somehow. > > Omar and Valéry already agreed to take care of the unfuzzy. Omar, > Valéry, if you have a second thought, I'm still ready to help (in any > way). I do share Joey's concern, and believe that a typographic > improvement to the documentation shouldn't cost a lack of translation. > > Valéry, I believe that you can safely apply my previous patch on reply > to your [LCFC] <4cbb3226.6010...@tilapin.org>: many changes still need > to be done, but some of debhelper(1) strings will just have to be unmark > fuzzy (I may explain myself better in French). > > Joey, when do you intend to upload, or on the other hand, Omar, Valery, > when can you send your PO files updated? > > Regards > > David > signature.asc Description: OpenPGP digital signature
Bug#600883: debhelper: Please improve manual page typography
David Prévot wrote: > Omar and Valéry already agreed to take care of the unfuzzy. Omar, Er right, not only French but also Spanish. > Joey, when do you intend to upload, or on the other hand, Omar, Valery, > when can you send your PO files updated? I will be surpised if a new debhelper version is released prior to the next release of Debian. -- see shy jo signature.asc Description: Digital signature
Bug#600883: debhelper: Please improve manual page typography
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Hi, Le 05/11/2010 17:33, Joey Hess a écrit : > I do wonder about the poor translators, especially for French which was > going to get back to 100% in this release. It would be great if the > translations could be fixed up somehow. Omar and Valéry already agreed to take care of the unfuzzy. Omar, Valéry, if you have a second thought, I'm still ready to help (in any way). I do share Joey's concern, and believe that a typographic improvement to the documentation shouldn't “cost” a lack of translation. Valéry, I believe that you can safely apply my previous patch on reply to your [LCFC] <4cbb3226.6010...@tilapin.org>: many changes still need to be done, but some of debhelper(1) strings will just have to be unmark fuzzy (I may explain myself better in French). Joey, when do you intend to upload, or on the other hand, Omar, Valery, when can you send your PO files updated? Regards David -BEGIN PGP SIGNATURE- Version: GnuPG v1.4.10 (GNU/Linux) iEYEARECAAYFAkzUhfYACgkQ18/WetbTC/owAgCfWPIBVxOUFlsdFBgz6V32w2Gi 7Z0Ani3Sh1xcBqoCSVQrL1HGCJjO3TdW =Xe/L -END PGP SIGNATURE- -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org
Bug#600883: debhelper: Please improve manual page typography
David Prévot wrote: > Actually, there are some tips in uri(7) about this sort of convention, > but using this: only for > this directory seems weird, and using this convention everywhere might > make the manual quite ugly. Anyway, since you forgot this trailing dot > on purpose, I won't touch it (but I fail to understand the problem, since > * /usr/share/doc/debhelper/examples/ > * /usr/share/doc/debhelper/examples/. > * /usr/share/doc/debhelper/examples/./ > point to the same directory anyway). Right, but that fails if the thing at the end is a file, and using differing typography for the file and dir cases is asking to make mistakes. > Please find attached an updated patch to debhelper.pod, also including a > s/debian/Debian/ when it is not about a directory. If you don't have any > more concern about it, I'll proceed the other manual pages making > equivalent changes. I've applied your full patch now. I do wonder about the poor translators, especially for French which was going to get back to 100% in this release. It would be great if the translations could be fixed up somehow. -- see shy jo signature.asc Description: Digital signature
Bug#600883: debhelper: Please improve manual page typography
Le 20/10/2010 20:14, Joey Hess a écrit : > David Prévot wrote: >> - -supported by the -P flag. [...] "dh_installdocs -Pdebian/tmp", will >> +supported by the B<-P> flag. [...] B, will > > I'd rather not make that change, I suspect there are display systems or > screen readers where the fact that something is quoted is apparent, but > that it is bold is not. Sure I kept the quotes in top of bold when multiple words are quoted (for example "B" in this case). >> - -rules files that use [...] F >> +rules files that use [...] F. > > Similarly, it's easy to miss notcing that a trailing dot is not bold, so > I prefer to leave them off, or separate them by a space, or some other > thing like that in such cases. Actually, there are some tips in uri(7) about this sort of convention, but using this: only for this directory seems weird, and using this convention everywhere might make the manual quite ugly. Anyway, since you forgot this trailing dot on purpose, I won't touch it (but I fail to understand the problem, since * /usr/share/doc/debhelper/examples/ * /usr/share/doc/debhelper/examples/. * /usr/share/doc/debhelper/examples/./ point to the same directory anyway). Please find attached an updated patch to debhelper.pod, also including a s/debian/Debian/ when it is not about a directory. If you don't have any more concern about it, I'll proceed the other manual pages making equivalent changes. Regards David commit ed87331a52e8b2b7bfef18e193bdd05a22f6764d Author: David Prévot Date: Tue Oct 19 18:54:32 2010 -0400 Apply manual pages conventions As advised in man(1), always use: B type exactly as shown. I replace with appropriate argument. s/debian/Debian/ if needed. diff --git a/debhelper.pod b/debhelper.pod index b2f130b..0ebe1c8 100644 --- a/debhelper.pod +++ b/debhelper.pod @@ -4,26 +4,26 @@ debhelper - the debhelper tool suite =head1 SYNOPSIS -BI<*> [B<-v>] [B<-a>] [B<-i>] [B<-s>] [B<--no-act>] [B<-ppackage>] [B<-Npackage] [-Ptmpdir>] +BI<*> [B<-v>] [B<-a>] [B<-i>] [B<-s>] [B<--no-act>] [B<-p>I] [B<-N>I] [B<-P>I] =head1 DESCRIPTION -Debhelper is used to help you build a debian package. The philosophy behind +Debhelper is used to help you build a Debian package. The philosophy behind debhelper is to provide a collection of small, simple, and easily -understood tools that are used in debian/rules to automate various common +understood tools that are used in F to automate various common aspects of building a package. This means less work for you, the packager. -It also, to some degree means that these tools can be changed if debian +It also, to some degree means that these tools can be changed if Debian policy changes, and packages that use them will require only a rebuild to comply with the new policy. -A typical debian/rules file that uses debhelper will call several debhelper +A typical F file that uses debhelper will call several debhelper commands in sequence, or use L to automate this process. Examples of rules files that use debhelper are in F -To create a new debian package using debhelper, you can just copy one of -the sample rules files and edit it by hand. Or you can try the dh-make +To create a new Debian package using debhelper, you can just copy one of +the sample rules files and edit it by hand. Or you can try the B package, which contains a L command that partially -automates the process. For a more gentle introduction, the maint-guide debian +automates the process. For a more gentle introduction, the B Debian package contains a tutorial about making your first package using debhelper. =head1 DEBHELPER COMMANDS @@ -49,7 +49,7 @@ A few debhelper commands are deprecated and should not be used. =head2 Other Commands -If a program's name starts with "dh_", and the program is not on the above +If a program's name starts with B, and the program is not on the above lists, then it is not part of the debhelper package, but it should still work like the other programs described on this page. @@ -59,10 +59,10 @@ Many debhelper commands make use of files in F to control what they do. Besides the common F and F, which are in all packages, not just those using debhelper, some additional files can be used to configure the behavior of specific debhelper commands. These -files are typically named debian/package.foo (where "package" of course, +files are typically named debian/I.foo (where I of course, is replaced with the package that is being acted on). -For example, dh_installdocs uses files named debian/package.docs to list +For example, B uses files named F to list the documentation files it will install. See the man pages of individual commands for details about the names and formats of the files they use. Generally, these files will list files to act on, one file per line. Some @@ -70,22 +70,22 @@ programs in debhelper use pairs of files and destinations or slightly more complicated formats. Note th
Bug#600883: debhelper: Please improve manual page typography
David Prévot wrote: > - -supported by the -P flag. [...] "dh_installdocs -Pdebian/tmp", will > +supported by the B<-P> flag. [...] B, will I'd rather not make that change, I suspect there are display systems or screen readers where the fact that something is quoted is apparent, but that it is bold is not. > - -rules files that use [...] F > +rules files that use [...] F. Similarly, it's easy to miss notcing that a trailing dot is not bold, so I prefer to leave them off, or separate them by a space, or some other thing like that in such cases. -- see shy jo signature.asc Description: Digital signature
Bug#600883: debhelper: Please improve manual page typography
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Le 20/10/2010 18:31, Joey Hess a écrit : > David Prévot wrote: >> While reviewing manual pages translation, I noticed that some parts >> of the manual pages doesn't follow guidelines conventions available >> in man(1), and could be improved in order to make it easier to pick >> information in them. >> >> The attached patch is a review taking care of these conventions, only >> in debhelper(7), but I'm willing to provide you a review of the other >> manual pages if it's fine with you to apply them (and if some of them >> are not justified, please let me know so I won't propose them for the >> other pages). > > I find getting that exactly right to be tedious and hard, so if you > can supply patches, you're a better editor than I. :) > > I will apply such patches, just please let me know if the entire patch > is changes to markup, so I don't need to review it for content.. I did get rid of some quotes if they are implicit by the convention, for example : @@ -59,10 +59,10 @@ Many debhelper commands make use of files in [...] - -files are typically named debian/package.foo (where "package" [...] +files are typically named debian/I.foo (where I [...] or @@ -317,14 +317,14 @@ reality. [...] - -supported by the -P flag. [...] "dh_installdocs -Pdebian/tmp", will +supported by the B<-P> flag. [...] B, will and, didn't use F<> markup when I<> is used because I can't see a difference between those to in my usual viewers: debian/I.foo and F are used. I'm willing to provide patch with only markup (and quote) stuff, since the proposed patch seems to be OK with you, and eventually another patch if I have other sort of suggestion or correction like this trailing dot: - -rules files that use [...] F +rules files that use [...] F. So please don't apply the previously attached patch (I already spotted stuff to change), I will provide you a complete one with only markup stuff within a week. Regards David -BEGIN PGP SIGNATURE- Version: GnuPG v1.4.10 (GNU/Linux) iEYEARECAAYFAky/eXUACgkQ18/WetbTC/oR+wCfetxMkgmQm+G13liz4BZJFsoB 4nMAn1eX9G8ffRMUwPSJ177uD5NCyL8J =ruJv -END PGP SIGNATURE- -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org
Bug#600883: debhelper: Please improve manual page typography
David Prévot wrote: > While reviewing manual pages translation, I noticed that some parts > of the manual pages doesn't follow guidelines conventions available > in man(1), and could be improved in order to make it easier to pick > information in them. > > The attached patch is a review taking care of these conventions, only > in debhelper(7), but I'm willing to provide you a review of the other > manual pages if it's fine with you to apply them (and if some of them > are not justified, please let me know so I won't propose them for the > other pages). I find getting that exactly right to be tedious and hard, so if you can supply patches, you're a better editor than I. :) I will apply such patches, just please let me know if the entire patch is changes to markup, so I don't need to review it for content.. -- see shy jo signature.asc Description: Digital signature
Bug#600883: debhelper: Please improve manual page typography
Package: debhelper Version: 8.0.0 Severity: minor Tags: patch Hi, While reviewing manual pages translation, I noticed that some parts of the manual pages doesn't follow guidelines conventions available in man(1), and could be improved in order to make it easier to pick information in them. The attached patch is a review taking care of these conventions, only in debhelper(7), but I'm willing to provide you a review of the other manual pages if it's fine with you to apply them (and if some of them are not justified, please let me know so I won't propose them for the other pages). Regards David -- System Information: Debian Release: squeeze/sid APT prefers unstable APT policy: (600, 'unstable'), (500, 'testing'), (500, 'stable'), (150, 'experimental') Architecture: amd64 (x86_64) Kernel: Linux 2.6.34-1-amd64 (SMP w/1 CPU core) Locale: LANG=fr_FR.UTF-8, LC_CTYPE=fr_FR.UTF-8 (charmap=UTF-8) Shell: /bin/sh linked to /bin/dash Versions of packages debhelper depends on: ii binutils 2.20.1-15 The GNU assembler, linker and bina ii dpkg-dev 1.15.8.5 Debian package development tools ii file 5.04-5 Determines file type using "magic" ii html2text 1.3.2a-15 advanced HTML to text converter ii man-db2.5.7-6on-line manual pager ii perl 5.10.1-15 Larry Wall's Practical Extraction ii perl-base 5.10.1-15 minimal Perl system ii po-debconf1.0.16 tool for managing templates file t debhelper recommends no packages. Versions of packages debhelper suggests: ii dh-make 0.55 tool that converts source archives -- no debconf information *** /tmp/commit-730aec0 commit 730aec073c327ac597d71dd129a3fd29be8134fb Author: David Prévot Date: Tue Oct 19 18:54:32 2010 -0400 Apply manual pages conventions As advised in man(1), always use: Btype exactly as shown. I replace with appropriate argument. diff --git a/debhelper.pod b/debhelper.pod index b2f130b..bf3894e 100644 --- a/debhelper.pod +++ b/debhelper.pod @@ -4,26 +4,26 @@ debhelper - the debhelper tool suite =head1 SYNOPSIS -BI<*> [B<-v>] [B<-a>] [B<-i>] [B<-s>] [B<--no-act>] [B<-ppackage>] [B<-Npackage] [-Ptmpdir>] +BI<*> [B<-v>] [B<-a>] [B<-i>] [B<-s>] [B<--no-act>] [B<-p>I] [B<-N>I] [B<-P>I] =head1 DESCRIPTION -Debhelper is used to help you build a debian package. The philosophy behind +Debhelper is used to help you build a Debian package. The philosophy behind debhelper is to provide a collection of small, simple, and easily -understood tools that are used in debian/rules to automate various common +understood tools that are used in F to automate various common aspects of building a package. This means less work for you, the packager. -It also, to some degree means that these tools can be changed if debian +It also, to some degree means that these tools can be changed if Debian policy changes, and packages that use them will require only a rebuild to comply with the new policy. -A typical debian/rules file that uses debhelper will call several debhelper +A typical F file that uses debhelper will call several debhelper commands in sequence, or use L to automate this process. Examples of -rules files that use debhelper are in F +rules files that use debhelper are in F. -To create a new debian package using debhelper, you can just copy one of -the sample rules files and edit it by hand. Or you can try the dh-make +To create a new Debian package using debhelper, you can just copy one of +the sample rules files and edit it by hand. Or you can try the B package, which contains a L command that partially -automates the process. For a more gentle introduction, the maint-guide debian +automates the process. For a more gentle introduction, the B Debian package contains a tutorial about making your first package using debhelper. =head1 DEBHELPER COMMANDS @@ -49,7 +49,7 @@ A few debhelper commands are deprecated and should not be used. =head2 Other Commands -If a program's name starts with "dh_", and the program is not on the above +If a program's name starts with B, and the program is not on the above lists, then it is not part of the debhelper package, but it should still work like the other programs described on this page. @@ -59,10 +59,10 @@ Many debhelper commands make use of files in F to control what they do. Besides the common F and F, which are in all packages, not just those using debhelper, some additional files can be used to configure the behavior of specific debhelper commands. These -files are typically named debian/package.foo (where "package" of course, +files are typically named debian/I.foo (where I of course, is replaced with the package that is being acted on). -For example, dh_installdocs uses files named debian/package.docs to list +For example, B us
