Package: debian-reference
Severity: wishlist
Hi Osamu,
here some proposals for Appendix A.
diff -u and wdiff output attached.
Greetings
Merry christmas to you and your family
Holger
--
============================================================
Created with Sylpheed 3.2.0 under the new
D E B I A N L I N U X 7 . 0 W H E E Z Y !
Registered Linux User #311290 - https://linuxcounter.net/
============================================================
--- 99_appendix.txt 2013-12-26 12:33:19.257104018 +0100
+++ 99_appendix_proposal.txt 2013-12-26 13:00:55.385316263 +0100
@@ -7,7 +7,9 @@
=== The Debian maze
-The Linux system is a very powerful computing platform for a networked computer. However, learning how to use all its capabilities is not easy. Setting up the LPR printer with non-PostScript printer was a good example of stumble points. (There are no issues anymore since newer installations use new CUPS system.)
+The Linux system is a very powerful computing platform for a networked computer. However, learning how to use all its capabilities is not easy. Setting up the LPR printer queue with a non-PostScript printer was a good example of stumble points. (There are no issues anymore since newer installations use the new CUPS system.)
+### HW: "set up the ...-printer with a ...-printer" seems weird. -> printer queue
+### HW: + add a "the"
There is a complete, detailed map called the "SOURCE CODE". This is very accurate but very hard to understand. There are also references called HOWTO and mini-HOWTO. They are easier to understand but tend to give too much
detail and lose the big picture. I sometimes have a problem finding the right section in a long HOWTO when I need a few commands to invoke.
@@ -17,10 +19,19 @@
=== Copyright history
Debian Reference was initiated by Osamu Aoki <osamu at debian dot org> as a personal system administration memo. Many contents came from the knowledge I gained from http://lists.debian.org/debian-user/[the debian-user mailing list] and other Debian resources.
+### HW: this paragraph before seems weird to me: first you talk in the third person
+### HW: ("initiated by Osamu") and then suddenly in the first person ("Many contents came
+### HW: from the knowledge I gained from"). Of course, this situation can be found
+### HW: in other places in the DR as well, and it would be too much work to sync that,
+### HW: but in this case, where it appears directly together, it could/should be solved?
+### HW: Like this:
+### HW: "The Debian Reference was initiated by me, Osamu Aoki <osamu at debian dot org>, as a ... "
+### HW: ^^^
+### HW: "The" added as well
Following a suggestion from Josip Rodin, who was very active with the http://www.debian.org/doc/ddp[Debian Documentation Project (DDP)], "Debian Reference (version 1, 2001-2007)" was created as a part of DDP documents.
-After 6 years, Osamu realized that the original "Debian Reference (version 1)" was outdated and started to rewrite many contents. New "Debian Reference (version 2)" is released in 2008.
+After 6 years, I realized that the original "Debian Reference (version 1)" was outdated and started to rewrite many contents. New "Debian Reference (version 2)" is released in 2008.
The tutorial contents can trace its origin and its inspiration in followings.
@@ -62,4 +73,5 @@
=== Document format
The source of the English original document is currently written in http://packages.debian.org/search?keywords=asciidoc[AsciiDoc] text files. http://packages.debian.org/search?keywords=asciidoc[AsciiDoc] is used as convenience only since it is less typing than straight XML and supports table in the very intuitive format. You should think XML and PO files as real source files. Via build script, it is converted to DocBook XML format and automatically generated data are inserted to form a final Docbook XML source. This final Docbook XML source can be converted to HTML, plain text, PostScript, and PDF. Currently, only HTML and plain text conversions are enabled.
+### HW: mention epub format as well?
== Appendix A: Appendix
// vim: set sts=2 expandtab:
// Use ":set nowrap" to edit table
Here are backgrounds of this document.
=== The Debian maze
The Linux system is a very powerful computing platform for a networked computer. However, learning how to use all its capabilities is not easy. Setting up the LPR printer {+queue+} with {+a+} non-PostScript printer was a good example of stumble points. (There are no issues anymore since newer installations use {+the+} new CUPS system.)
{+### HW: "set up the ...-printer with a ...-printer" seems weird. -> printer queue
### HW: + add a "the"+}
There is a complete, detailed map called the "SOURCE CODE". This is very accurate but very hard to understand. There are also references called HOWTO and mini-HOWTO. They are easier to understand but tend to give too much
detail and lose the big picture. I sometimes have a problem finding the right section in a long HOWTO when I need a few commands to invoke.
I hope this "Debian Reference (version 2)" provides a good starting direction for people in the Debian maze.
=== Copyright history
Debian Reference was initiated by Osamu Aoki <osamu at debian dot org> as a personal system administration memo. Many contents came from the knowledge I gained from http://lists.debian.org/debian-user/[the debian-user mailing list] and other Debian resources.
{+### HW: this paragraph before seems weird to me: first you talk in the third person
### HW: ("initiated by Osamu") and then suddenly in the first person ("Many contents came
### HW: from the knowledge I gained from"). Of course, this situation can be found
### HW: in other places in the DR as well, and it would be too much work to sync that,
### HW: but in this case, where it appears directly together, it could/should be solved?
### HW: Like this:
### HW: "The Debian Reference was initiated by me, Osamu Aoki <osamu at debian dot org>, as a ... "
### HW: ^^^
### HW: "The" added as well+}
Following a suggestion from Josip Rodin, who was very active with the http://www.debian.org/doc/ddp[Debian Documentation Project (DDP)], "Debian Reference (version 1, 2001-2007)" was created as a part of DDP documents.
After 6 years, [-Osamu-] {+I+} realized that the original "Debian Reference (version 1)" was outdated and started to rewrite many contents. New "Debian Reference (version 2)" is released in 2008.
The tutorial contents can trace its origin and its inspiration in followings.
- "http://www.ibiblio.org/pub/Linux/docs/linux-doc-project/users-guide/user-beta-1.pdf.gz[Linux User@@@sq@@@s Guide]" by Larry Greenfield (December 1996)
* obsoleted by "Debian Tutorial"
- "http://www.debian.org/doc/manuals/debian-tutorial/[Debian Tutorial]" by Havoc Pennington. (11 December, 1998)
* partially written by Oliver Elphick, Ole Tetlie, James Treacy, Craig Sawyer, and Ivan E. Moore II
* obsoleted by "Debian GNU/Linux: Guide to Installation and Usage"
- "http://archive.debian.net/woody/debian-guide[Debian GNU/Linux: Guide to Installation and Usage]" by John Goerzen and Ossama Othman (1999)
* obsoleted by "Debian Reference (version 1)"
The package and archive description can trace some of their origin and their inspiration in following.
- "http://www.debian.org/doc/manuals/debian-faq/[Debian FAQ]" (March 2002 version, when this was maintained by Josip Rodin)
The other contents can trace some of their origin and their inspiration in following.
- "http://packages.debian.org/search?keywords=debian-reference@@@amp@@@searchon=sourcenames@@@amp@@@exact=1@@@amp@@@suite=all@@@amp@@@section=all[Debian Reference] (version 1)" by Osamu Aoki (2001â2007)
* obsoleted by this new "Debian Reference (version 2)"
The previous "Debian Reference (version 1)" was created with many contributors.
- the major contents contribution on network configuration topics by Thomas Hood
- significant contents contribution on X and VCS related topics by Brian Nelson
- the help on the build scripts and many content corrections by Jens Seidel
- extensive proofreading by David Sewell
- many contributions by the translators, contributors, and bug reporters
Many manual pages and info pages on the Debian system were used as the primary references to write this document. To the extent Osamu Aoki considered within the http://en.wikipedia.org/wiki/Fair_use[fair use], many parts of them, especially command definitions, were used as phrase pieces after careful editorial efforts to fit them into the style and the objective of this document.
// Error: "the fair quotation stature" / Correct: "the fair quote statute" -> Now I have "the fair use".
The gdb debugger description was expanded using http://wiki.debian.org/HowToGetABacktrace[Debian wiki contents on backtrace] with consent by Ari Pollak, Loïc Minier, and Dafydd Harries.
Contents of "Debian Reference (version 2)" are mostly my own work except as mentioned above. These has been updated by the contributors too.
The author, Osamu Aoki, thanks all those who helped make this document possible.
=== Document format
The source of the English original document is currently written in http://packages.debian.org/search?keywords=asciidoc[AsciiDoc] text files. http://packages.debian.org/search?keywords=asciidoc[AsciiDoc] is used as convenience only since it is less typing than straight XML and supports table in the very intuitive format. You should think XML and PO files as real source files. Via build script, it is converted to DocBook XML format and automatically generated data are inserted to form a final Docbook XML source. This final Docbook XML source can be converted to HTML, plain text, PostScript, and PDF. Currently, only HTML and plain text conversions are enabled.
{+### HW: mention epub format as well?+}
