Eduard Bloch <[EMAIL PROTECTED]> writes: > #include <hallo.h> > * Jari Aalto [Sat, Feb 04 2006, 04:36:55PM]: > >> Eduard Bloch <[EMAIL PROTECTED]> writes: >> >> > #include <hallo.h> >> > * Jari Aalto [Sat, Feb 04 2006, 01:16:06PM]: >> > >> >> Package: svn-buildpackage >> >> Version: 0.6.14 >> >> Severity: wishlist >> >> >> >> The manual pages in current form are very clinical and suppose high >> >> technical level of understanding how the development process goes. It >> >> would be good if in each manual page, there were section >> > >> > Have you visited /usr/share/doc/svn-buildpackage already? Is that >> > sufficient or do you want more? >> >> Yes I have. I wasn't clear enough in the message. I wold like to >> see some kind of "crash course" or "reminder" in the EXAMPLES section >> of the man pages, so that the "standard work flow" could be seen >> in one glance. > > Reality check please! Do you expect the g++ manpage to be a C syntax > reference and describe every bit of OOP, plus make tutorial and > autotools guide to explain the standard workflow?
I was addressing the typical use of the commands. Now it only contains technical data and syntax. For example rsync(1) man pages are quite good in presenting the use of the command. It would make the documentation better. >> I Mean: >> >> 1. Hack Debian >> 2. BE away in other projects >> 3. .. back to debian after months >> 4. ?? Eh, I've forgotten the routine >> 5. ?? Hm, the command was XXX, let's read man page, maybe it >> brings to my mind... >> 6. Erm, no EXAMPLES section here ... > > SEP. If you forgot the knowledge, go the same way as the first time to > get it. I am not there to teach everyone doing everything and looking in > new-maint-guide or dev-reference from time to time is not a reason to be > ashamed. There is no need to take my example from a perspective that is not appropriate. I did not suggest any teaching, but improving the quality of the manual. Let's not discuss the politics "people should read the manual". It is different form one that ahsnät done anything yet and need to learm, than from someone that has aleray done but needs a reminder how to recall the once learned things. The EXAMPLES would suit to that kind of thing as well, as well as for quick first guide. >> The /usr/share/doc/svn-buildpackage could be the full manual >> and EXAMPLES would give typical examples how commands are applied. > > If you wish to see a noob-style guide, write one and I most likely would > add it to the package. I'm not referring to noob guide. No matter how experienced one is, there are so many tools that one simply cannot remmeber all the details involved. Good manual pages contains always typical situations where the typical usage is demontrated with examples. Kindly add those examples, which enhance uality of the pages. In depth explanation can be left in the /usr/share/doc Jari
