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

Re: maint-guide: English source update suggestions



Hi,

With aftermath of the earthquake, I am a bit tired with crowded commuter
train ....

On Mon, Mar 14, 2011 at 07:34:21PM +0100, Innocent De Marchi wrote:
> Hi Osamu,
> 
> Please respond quickly to my suggestions.
> 
> >
> > | --- maint-guide.en.sgml 2011-01-30 17:25:45.000000000 +0100
> > | +++ maint-guide.en-original_contributions.sgml  2011-01-30 18:57:37.000000000 +0100
> > | @@ -96,8 +96,9 @@
> > |    <p>Newer versions of this document should always be available online at
> > |    <url name="http://www.debian.org/doc/maint-guide/"; id="http://www.debian.org/doc/maint-guide/";>
> > |    and in the <package/maint-guide/ package.
> > | -  <!-- Translation in <this language> is also available in the
> > | -       <package/maint-guide-xy/ package. -->
> > | +  The translations (perhaps without upgrading to the latest version of the
> > | +  original in English) are distributed in the package <package>maint-guide-xx</package>
> > | +  (where xx is the language code).
> >
> > This one will be dealt a bit differently for translation.  You will see new
> > easier translation specific addendum method in my updated build script.
> 
> OK
> 
> >
> > | @@ -268,7 +270,10 @@
> > |
> > |    <item><strong>source package</strong>: A source package is a set of files
> > |    which contain code and data which you can compile and process into execution
> > | -  programs and formatted documents.  It usually comes as a combination of
> > | +  programs and formatted documents.
> > | +  <footnote><p>This document is the result of processing a <file>.po</file> file format
> > | +  to get a <file>pdf</file> file or a set of files in HTML format.</p></footnote>.
> > | +  It usually comes as a combination of
> > |    <file>*.orig.tar.gz</file>, <file>*.debian.tar.gz</file> (or
> > |    <file>*.diff.gz</file>), and <file>*.dsc</file>.  Some other archive and
> > |    compression methods may be used, too.
> >
> > If I were to add this, "processing a <file>maint-guide.en.dbk</file> file and
> > <file>maint-guide.??.po</file>" should be the words to describe source files
> > for the translation.  I see your thought to address specifics for this package.
> > But is this really essential to mention this?
> 
> You have more experience in this, your decision will be successful
> 
> >
> > | @@ -287,7 +292,7 @@
> > |    <list>
> > |
> > |    <item><strong>upstream author</strong>: The person who made the original
> > | -  program.
> > | +  program (or original documents in the case of documentation packages).
> > |
> > |    <item><strong>upstream maintainer</strong>: The person who currently
> > |    maintains the program.
> >
> > Hmmm... you really want to explain how this doc package is packaged.  But this
> > document is more about execution program package.  Putting too much information
> > tends to loose focus and confused audience.
> 
> OK.
> 
> >
> > | @@ -310,7 +315,7 @@
> > |
> > |    </list>
> > |
> > | -  <p>There are several version names used around Debian.
> > | +  <p>There are several version names (see <ref id="namever">) used around Debian.
> > |
> > |    <list>
> > |    <item><strong>upstream source version</strong>: The upstream source version is referred as <tt><var>version</var></tt>.
> >
> > Link to <ref id="namever"> is a good idea.  But link to
> > http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Version
> > is something needed too.  How to get them all linked nicely..  let me
> > think...
> 
> OK.
> 
> >
> > | @@ -350,7 +356,9 @@
> > |    <file>/usr/share/doc/debian</file>, <file>&autotools-dev;</file>,
> > |    <file>/usr/share/doc/<var>package</var>/*</file>
> > |    files and the <prgn>man</prgn>/<prgn>info</prgn> pages for all the programs mentioned in this document.
> > | -  See all the information at <url id="&nm-home;">.
> > | +  See all the information at <url id="&nm-home;">
> > | +  <footnote><p>restricted access to persons who are in the program
> > | +  to access to DD or DM.</p></footnote> and <url id="&mentors-faq;">.
> > |    <p>Making a small test package is good way to learn details of packaging.
> > |    Inspecting existing well maintained packages is the best way to learn how other
> >
> > <!ENTITY nm-home              "http://nm.debian.org/";>
> >
> > &newmaint; is part of &nm-home;.  &mentors-faq; is extensive source of info.  I
> > do not want to duplicate in this way.  It is good idea to mention &mentors-faq;
> > though.  Let me think.
> 
> OK.
> 
> >
> > I do not understand your addition of <footnote>...</footnote>.  I think you try
> > to say something along:
> >
> > || See all the information at <url id="&nm-home;"> and and
> > || <url id="&mentors-faq;"> to gain upload access to the Debian archive as DD or
> > || DM.
> >
> 
> OK.
> 
> >
> > | @@ -358,12 +366,14 @@
> > |
> > |    <p>If you still have questions about packaging that you couldn't find answers to
> > |    in the available documentation and web resources, you can ask them on the Debian Mentors' mailing list
> > | -  at <url id="http://lists.debian.org/debian-mentors/"; name="debian-mentors@lists.debian.org">. The more experienced Debian
> > | +  at <url id="http://lists.debian.org/debian-mentors/"; name="debian-mentors@lists.debian.org">
> > | +  and the IRC #debian-mentors (may have a IRC of mentors in your language).
> > | +  The more experienced Debian
> > |    developers will gladly help you, but do read at least some of the
> > |    documentation before asking a question!
> > |
> > |    <p>See <url id="http://lists.debian.org/debian-mentors/";> for more
> > | -  information about this mailing list.
> > | +  information about this mailing list and the IRC channel #debian-mentors.
> > |
> > |    <p>When you receive
> > |    a bug report (yes, actual bug reports!), you will know that it is time for you
> >
> > I got your point on IRC.  But inclusion of "...mentors in your language" can be
> > done a bit differently.  I will think about it.
> 
> OK.
> 
> >
> > | @@ -389,7 +399,8 @@
> > |
> > |    <chapt id="first">First steps
> > |
> > | -  <p>Let's try to make your own package (or, better even, adopt an existing one).
> > | +  <p>Let's try to make your own package (or, better even, adopt an existing one,
> > | +  see <url id="http://wnpp.debian.net/"; name="Debian Packages that Need Lovin'">).
> > |
> > |    <sect id="choose">Choose your program
> > |
> >
> > I see your point.  But following "2.1 Choose your program" list this and more.
> > Isn't this too much duplication?
> 
> Yes, If it is true
> 
> 
> >
> > | @@ -406,8 +417,9 @@
> > |    <url name="Debian QA Group" id="http://qa.debian.org/";>, you may
> > |    be able to pick it up if it's still available (check the ownership status
> > |    at <url name="Debian Bug report logs: Bugs in package wnpp in unstable" id="http://bugs.debian.org/wnpp";>).
> > | -  You may also adopt a package for which the corresponding maintainer has filed
> > | +  You may also adopt a package for which the corresponding maintainer (or a DD) has filed
> > |    a "Request for Adoption" (<strong>RFA</strong>).
> >
> > This could be DM.  So let's leave this without "(or a DD)" as was.
> 
> OK.
> 
> >
> > | +  See <url id="http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=594398";> for an example.
> >
> > Can you elaborate why you picked this example from other possible candidates?
> 
> For no particular reason. I was looking to adopt some orphan package
> and put this link. Surely there are other more appropriate!
> 
> >
> > |    <p>Several different views of orphaned or RFA'ed packages are available at:
> > |    <list>
> > | @@ -427,12 +439,27 @@
> > |     You can do that in various ways.
> > |     <list>
> > |     <item>taking over orphaned, yet actively used, packages
> > | +   (look at the Popularity Contest Stats of the package in
> > | +   <url id="http://qa.debian.org/popcon.php";>)
> >
> > popcon gives us popularity but this interface is not the best entry to find
> > actively used packages.
> 
> Yes, I put some other link.
> 
> >
> > |     <item>joining <url name="packaging teams" id="http://wiki.debian.org/Teams";>
> > |     <item>triaging bugs of very popular packages
> > |     <item>preparing <url name="QA or NMU uploads" id="http://www.debian.org/doc/developers-reference/pkgs.html#nmu-qa-upload";>
> > | +   <footnote><p>QA packages are maintained by the Debian Quality Group
> > | +   and they are orphans, and NMU are packages that do not currently
> > | +   have an maintainer.</p></footnote>.
> >
> > You insist to put this dspite I have link to "5.11.6. NMUs vs QA upload" in
> > developers-reference.
> 
> OK.
> 
> >
> > |     </list>
> > |
> > | -  <p>If you are able to adopt the package, get the sources (with something
> > | +  <p>If you are able to adopt the package, get the sources
> > | +  <footnote><p>The most direct way to adopt an orphaned package
> > | +  is to consult the list of orphaned packages <url id="http://wnpp.debian.net/?type[]=O&project=&description=&owner[]=yes&owner[]=no&col[]=dust&col[]=type&col[]=description&col[]=installs&sort=project";>.
> > | +  In these lists, package name refers directly to the bug report
> > | +  states that as an orphan. If you decide to adopt a package,
> > | +  send an email to the list with the number of bug report requesting
> > | +  the change of title of the error report
> > | +  (see <url id="http://www.debian.org/devel/wnpp/index.html#howto-o";>).
> > | +  With this notification, the other contributors know that you're
> > | +  working on the package.</p></footnote>
> > | +  , get the sources (with something
> >
> > I see your point to explain more around here.   Quite frankly, this maint-guide
> > is not primary place to describe NMU nor WNPP nor DM process.  I think we
> > should not duplicate too much contents.  That will lead to unmaintainable
> > document. This should only give pointer to such info and this should focus on
> > what it is good .... technical aspect of simple packaging.  Let me use this as
> > reference and trim them down a bit.
> 
> Yes, but for people starting out, this type of information (without
> having to consult other sources) may be useful. But you can cut the
> text: no problem.
> 
> >
> > |    like "<tt>apt-get source <var>packagename</var></tt>") and examine them. This document
> > |    unfortunately doesn't include comprehensive information about adopting
> > |    packages. Thankfully you shouldn't have a hard time figuring out how the
> > | @@ -526,7 +553,7 @@
> > |    unpack it with appropriate tools and repack it, too.
> > |
> > |    <p>As an example, I'll use a program called <prgn>gentoo</prgn>, an X GTK+ file
> > | -  manager.<footnote>This program is already packaged.  Current version 0.15.3 has changed
> > | +  manager.<footnote>This program is already packaged.  Current version 0.19.8 has changed
> > |    substantially from the version 0.9.12 in the following examples.</footnote>
> >
> > Thanks for finding this out.  Since 0.19.8 may not be "Current", we may want to use "More recent".
> > Then we do not need to update this version number often.
> 
> Yes, update version is a drag. Maybe they could put a link to PTS
> (http://packages.qa.debian.org/g/gentoo.html)

Good suggestion ... need some text changes ...

> > |    <p>Create a subdirectory under your home directory named <file>debian</file> or <file>deb</file>
> > | @@ -555,7 +582,11 @@
> > |    directory; you won't be doing that, but more on that later in <ref
> > |    id="destdir">).
> > |
> > | -  <p>Simple programs come with a <file>Makefile</file> file in them and can be
> > | +  <p>The process varies from program to program, but most modern
> > | +  programs come with a script <file>configure</file> to configure
> > | +  the sources for your system and ensures that the system is able
> > | +  to compile.
> > | +  Simple programs come with a <file>Makefile</file> file in them and can be
> > |    compiled simply with "<tt>make</tt>".  Some of them support
> >
> > How about ...:
> >
> > <p>The build process of programs varies from program to program.  Simpler
> > programs come with a <file>Makefile</file> file in them.  Many modern programs
> > come with a script <file>configure</file> which creates a <file>Makefile</file>
> > file customized for your system upon its execution.  These programs can be
> > build simply with "<tt>make</tt>" using the <file>Makefile</file> file.
> 
> OK.
> 
> >
> > <p>Some of them support
> > |    "<tt>make check</tt>", which runs included self-checks. Installation to the
> > |    destination directories is usually done with "<tt>make install</tt>".
> > | @@ -759,7 +790,10 @@
> > |    <tt>--addmissing</tt> option again in a Debian package
> > |    source tree.
> > |
> > | -  <p>Updating an existing package may get complicated since it may be using
> > | +  <p>Please note that you should run <prgn>dh_make</prgn> only once,
> > | +  and not behave correctly if you do it again in the same directory
> > | +  with the <file>debian</file> directory already generated.
> > | +  Updating an existing package may get complicated since it may be using
> > |    older techniques.  Please stick with fresh packaging cases for now to learn
> > |    basics.  I will come back to explain it later in <ref id="update">.
> >
> > I intentinally removed this warning... We have -a, --addmissing option now.
> 
> OK.
> 
> >
> > | @@ -829,7 +863,16 @@
> > |          install gentoorc-example $(HOME)/.gentoorc
> > |  </example>
> > |
> > | -<p>Ask <prgn>quilt</prgn> to refresh the patch to create <file>debian/patches/fix-gentoo-target.patch</file> and add its description.
> > | +<p>Ask <prgn>quilt</prgn> to refresh the patch to create <file>debian/patches/fix-gentoo-target.patch</file> and add its description
> > | +<footnote><p>It is advised that after the execution of each order,
> > | +you carefully consider the changes. In this example, the
> > | +<file>debian/patches/fix-gentoo-target.patch</file> file is generated:
> > | +which is a text file that contains the changes into the
> > | +<file>Makefile</file> file. Lines to delete are preceded by
> > | +a sign <tt>-</tt> and then the new lines are preceded by a <tt>+</tt>. At the head
> > | +of the patch file is the description of the patch. The descriptions
> > | +must be in English. See <url name="Patch Tagging Guidelines" id="http://dep.debian.net/deps/dep3/";>
> > | +for more details.</p></footnote>..
> >
> > I like dep3 reference but explanation of patch seems exessive.
> 
> OK.
> >
> > |    <item>The source follows the Filesystem Hierarchy Standard (FHS).
> > |    </list>
> > |    <p>Programs that use GNU <prgn>autoconf</prgn> <em>automatically</em> follow
> > | @@ -901,6 +945,13 @@
> > |    strings like
> > |    <tt>/home/me/deb/<var>package</var>-<var>version</var>/usr/share/<var>package</var></tt>
> > |    into the package file.
> > | +  The <file>.deb</file> files are compressed files. If you look
> > | +  the <file>.deb</file> file with a compressed files management program
> > | +  you will see a zip file containing "data.tar.gz" which contains
> > | +  a replica of the directory structure starting at the root directory.
> > | +  The analysis of the contents of the "debian" directory after
> > | +  the construction of the <file>.deb</file> file and the content
> > | +  of the <file>.deb</file> package file can you help to understand the process.
> >
> > Let me think what to do.  I intentinally left this technical aspect out since
> > readers are expected to read dpkg document etc.
> 
> OK:
> 
> >
> > |    <p>Here's the relevant part of <package>gentoo</package>'s
> > |    <file>Makefile</file> file
> > | @@ -955,10 +1006,13 @@
> > |  $ grep -nr -e 'usr/local/lib' --include='*.[c|h]' .
> > |  </example>
> > |
> > | -  <p><prgn>grep</prgn> will run recursively through the source tree and tell
> > | -  you the filename and the line number for all matches.
> > | +  <p><prgn>grep</prgn> will run recursively through the source tree
> > | +  searching files with <tt>.c</tt> and <tt>.h</tt> extension and show
> > | +  you the filename and the line number when it finds a match with the
> > | +  chain <file>usr/local/lib</file>.
> >
> > With s/chain/string/, this is good suggestion for novice.  Do we need to be so
> > wordy for "grep", that is somehing I wonder.  Why not read manpage if the
> > reader is new maint candidate...
> 
> OK.
> 
> >
> > |    <p>Edit those files and in those lines replace <tt>usr/local/lib</tt> with <tt>usr/lib</tt>.
> > | +  Can be done automatically with this order:
> >
> > How aboout:
> >
> > This can be done automatically as follows:
> >
> > (We Japanese and Spanish people tend to drop obvious subject words.... but
> > Anglophone does not like it.)
> 
> True!
> 
> > ==== Following are not checked well ====
> 
> OK.
> And continue in the next chapter
> 
> Regards!
> 
> I. De Marchi

Good night ... I need to wake up 4:30 in the morning for commute ...


Reply to: