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: