Re: maint-guide: English source update suggestions
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)
>
> | <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
Reply to: