Don't flame me, I'm just trying to understand packages and their updates, I'm frustrated! I don't know how many of the linux packages out there have either incomplete or out of date documentation, but i'm getting tired of having to trace through a number of sources, maintainers, lists, earlier sources, obsolete versions, etc., just to work out if a package i've been recomended to try to do a particular task can give me the results I want for my clients. I'd just love to have someone with authority (such as LT himself) come out with the command "No package is to be considered for inclusion at the release stage unless the Documentation is Complete and up to date." Maybe, someone in Novell-SuSE could have the responsability for our community end and butt-kick. I know they are not the packager / supplier of the source in most instances so the yell is not at them directly, but the "listing" of packages with insufficent or out of date documentation, plus the threat of non-inclusion or non-certification, might just get some of these programmers off their buts and help us poor middle-users to understand their capabilities better. scsijon
On Sun, Apr 23, 2006 at 07:05:41PM +1000, scsijon wrote:
Don't flame me,
I'm just trying to understand packages and their updates, I'm frustrated!
I don't know how many of the linux packages out there have either incomplete or out of date documentation, but i'm getting tired of having to trace through a number of sources, maintainers, lists, earlier sources, obsolete versions, etc., just to work out if a package i've been recomended to try to do a particular task can give me the results I want for my clients.
Documentation might still not tell you that. You need to test-run it to be sure.
I'd just love to have someone with authority (such as LT himself) come out with the command
"No package is to be considered for inclusion at the release stage unless the Documentation is Complete and up to date."
That would stop the complete Linux distributions. I asume that you also want it to be translated into all languages, or are you happy to translate French or Spannish documentation into your own? It is nice to want. It also is completely unrealistic to do. I am sure less then 1% have complete and up to date documentation. And that most likely only for smaller programs. houghi -- Nutze die Zeit. Sie ist das Kostbarste, was wir haben, denn es ist unwiederbringliche Lebenszeit. Leben ist aber mehr als Werk und Arbeit, und das Sein wichtiger als das Tun - Johannes Müller-Elmau
At 02:29 PM 24/04/2006, houghi wrote:
Don't flame me,
I'm just trying to understand packages and their updates, I'm frustrated!
I don't know how many of the linux packages out there have either incomplete or out of date documentation, but i'm getting tired of having to
On Sun, Apr 23, 2006 at 07:05:41PM +1000, scsijon wrote: trace through
a number of sources, maintainers, lists, earlier sources, obsolete versions, etc., just to work out if a package i've been recomended to try to do a particular task can give me the results I want for my clients.
Documentation might still not tell you that. You need to test-run it to be sure.
I'd just love to have someone with authority (such as LT himself) come out with the command
"No package is to be considered for inclusion at the release stage unless the Documentation is Complete and up to date."
That would stop the complete Linux distributions. I asume that you also want it to be translated into all languages, or are you happy to translate French or Spannish documentation into your own?
nah, just sanscrit
It is nice to want. It also is completely unrealistic to do. I am sure less then 1% have complete and up to date documentation. And that most likely only for smaller programs.
then it's time to get it right
Hi, On Sunday, April 23, 2006 at 19:05:41, scsijon wrote:
might just get some of these programmers off their buts and help us poor middle-users to understand their capabilities better.
Help yourself. Get off _your_ butt and offer projects to write documentation :) Henne -- Henne Vogelsang, http://hennevogel.de "To die. In the rain. Alone." Ernest Hemingway
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 The Monday 2006-04-24 at 10:57 +0200, Henne Vogelsang wrote:
Help yourself. Get off _your_ butt and offer projects to write documentation :)
I'm collaborating in that respect (doing translations), but it is quite difficult to document a program you don't know what it does. Only the developpers can do that, I'm afraid. I can polish and expand a write up, but the first go has to be done by the developpers. - -- Cheers, Carlos Robinson -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.0 (GNU/Linux) Comment: Made with pgp4pine 1.76 iD8DBQFETKxItTMYHG2NR9URAq4UAJ4rBzMUo9bWg7FRWNFxXq3YeKjtnQCeJnpU ZuxHrY3Kr6wmIsM7dXCWsSM= =RxkO -----END PGP SIGNATURE-----
Hi, On Monday, April 24, 2006 at 12:45:27, Carlos E. R. wrote:
The Monday 2006-04-24 at 10:57 +0200, Henne Vogelsang wrote:
Help yourself. Get off _your_ butt and offer projects to write documentation :)
I'm collaborating in that respect (doing translations), but it is quite difficult to document a program you don't know what it does. Only the developpers can do that, I'm afraid. I can polish and expand a write up, but the first go has to be done by the developpers.
The point is to write to the developers offering your help to document things. They can point you to already existing documentation that needs to be expanded, updated (and in what way) or help you gathering information from the source code or send their documentation that they didnt published because its not done yet, they can answer questions about the app that you have or or or or or. The real point is that you dont get anything documented by crying out loud and complaining. This is OSS: do or die :) Henne -- Henne Vogelsang, Core Services "Rules change. The Game remains the same." - Omar (The Wire)
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 The Monday 2006-04-24 at 13:02 +0200, Henne Vogelsang wrote:
The point is to write to the developers offering your help to document things. They can point you to already existing documentation that needs to be expanded, updated (and in what way) or help you gathering information from the source code or send their documentation that they didnt published because its not done yet, they can answer questions about the app that you have or or or or or.
I would prefer a centralised or coordinated method: people that can write, or translate or whatever registering somewhere, and developpers asking there for some one. Or users saying which project they want documented first. Also writers need writing methods (software) that they can like. Not programmers tools for writing ;-)
The real point is that you dont get anything documented by crying out loud and complaining. This is OSS: do or die :)
Agreed. - -- Cheers, Carlos Robinson -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.0 (GNU/Linux) Comment: Made with pgp4pine 1.76 iD8DBQFETNnytTMYHG2NR9URAmYfAJ9gHRz4ypYGIFk0tRou5vbIPfFCdgCdEhIq aZpZ0E3kHU0nTTD/TlxSNn8= =x8gY -----END PGP SIGNATURE-----
On Mon, Apr 24, 2006 at 04:00:16PM +0200, Carlos E. R. wrote:
I would prefer a centralised or coordinated method: people that can write, or translate or whatever registering somewhere, and developpers asking there for some one. Or users saying which project they want documented first.
http://www.tldp.org/ might be a nice start. If they do not do what you want, ask them to change. If they are unwilling to do that, start your own project. houghi -- Nutze die Zeit. Sie ist das Kostbarste, was wir haben, denn es ist unwiederbringliche Lebenszeit. Leben ist aber mehr als Werk und Arbeit, und das Sein wichtiger als das Tun - Johannes Müller-Elmau
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 The Monday 2006-04-24 at 16:30 +0200, houghi wrote:
On Mon, Apr 24, 2006 at 04:00:16PM +0200, Carlos E. R. wrote:
I would prefer a centralised or coordinated method: people that can write, or translate or whatever registering somewhere, and developpers asking there for some one. Or users saying which project they want documented first.
http://www.tldp.org/ might be a nice start. If they do not do what you want, ask them to change. If they are unwilling to do that, start your own project.
Hum! I _am_ already translating a project, ie, I'm doing my bit. I went out, choosed a project at random, tried the translation software (kbabel), asked for permission, and started translating. Bu it doesn't work that way you say. I'm not interested in starting anything. It is this way: I can translate, and perhaps document. I'm available. But, if things are not easy enough, if I'm not enticed, I will not go. As simple as that. I did have a look at tldp, by the way, at the Spanish side of it. I will look again when I finish the package I'm working at now. My impression was that there wasn't much being done. Some translations are years old and obsolete. If there are so few writers and translators, perhaps there is something wrong that don't attract these people to help. So, something has probably got to be done to attract them. One of my guess is that good translators translate for a living and are not interested in working for free (as in beer). - -- Cheers, Carlos Robinson -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.0 (GNU/Linux) Comment: Made with pgp4pine 1.76 iD8DBQFETWAgtTMYHG2NR9URAg+eAJ0UYP4DCkUiMYpK5yrJ1zb60BbDeQCfbI8N OsWojRInPqBRhE4y44BxSoI= =qa0A -----END PGP SIGNATURE-----
Am Dienstag, den 25.04.2006, 01:32 +0200 schrieb Carlos E. R.:
If there are so few writers and translators, perhaps there is something wrong that don't attract these people to help. So, something has probably got to be done to attract them. One of my guess is that good translators translate for a living and are not interested in working for free (as in beer).
I don't know about "good". Anyhow, I would like to do some translation work for an open source project too, but then again, taking a look at a random man page frustrates more than anything: Even for a native English speaker, who is not exactly a Linux-buff though, the average man page is simply gibberish (try man mount, or - for the real brave - man rpm) And what helps a translation of an outdated or plain wrong documentation. Example: Try to find a complete list of evolution's command line options. The help centre lists some options and refers to "entering the command man evolution or evolution --help" for a full list. Yeah right. A man page for evolution simply does not exist, and evolution --help does not even list the options given in the help centre (but a lot of other stuff). Andreas
On Mon, Apr 24, 2006 at 05:23:39PM -0700, Andreas wrote:
I don't know about "good". Anyhow, I would like to do some translation work for an open source project too, <snip>
Start with openSUSE.org. Many pages to translate. houghi -- Nutze die Zeit. Sie ist das Kostbarste, was wir haben, denn es ist unwiederbringliche Lebenszeit. Leben ist aber mehr als Werk und Arbeit, und das Sein wichtiger als das Tun - Johannes Müller-Elmau
Am Dienstag, den 25.04.2006, 03:07 +0200 schrieb houghi:
Start with openSUSE.org. Many pages to translate.
houghi, I actually looked into it, but didn't you know, the instructions about how to take part in the translation effort were more than unclear, and my email to the opensuse-wiki-mailinglist hasn't been answered yet. I guess either the German translations are already well maintained or everyone is busy with the last touches for the SUSE 10.1 final. Gruß Andreas
On Tue, Apr 25, 2006 at 08:13:42PM -0700, Andreas wrote:
Am Dienstag, den 25.04.2006, 03:07 +0200 schrieb houghi:
Start with openSUSE.org. Many pages to translate.
houghi, I actually looked into it, but didn't you know, the instructions about how to take part in the translation effort were more than unclear, and my email to the opensuse-wiki-mailinglist hasn't been answered yet. I guess either the German translations are already well maintained or everyone is busy with the last touches for the SUSE 10.1 final.
Well, you got your answer. ;-) houghi -- Nutze die Zeit. Sie ist das Kostbarste, was wir haben, denn es ist unwiederbringliche Lebenszeit. Leben ist aber mehr als Werk und Arbeit, und das Sein wichtiger als das Tun - Johannes Müller-Elmau
Andreas wrote:
And what helps a translation of an outdated or plain wrong documentation.
then you should join the ldp (Linux Documentation Project) (http://tldp.org) for sure, the documentation work on linux is still lacking, but it's so much better than 10 years ago :-)) jdd -- http://www.dodin.net http://dodin.org/galerie_photo_web/expo/index.html http://lucien.dodin.net http://fr.susewiki.org/index.php?title=Gérer_ses_photos
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 The Monday 2006-04-24 at 17:23 -0700, Andreas wrote:
Am Dienstag, den 25.04.2006, 01:32 +0200 schrieb Carlos E. R.:
If there are so few writers and translators, perhaps there is something wrong that don't attract these people to help. So, something has probably got to be done to attract them. One of my guess is that good translators translate for a living and are not interested in working for free (as in beer).
I don't know about "good".
Me neither :-P It more difficult to translate than it seems. I can read, write, talk in English quite fluently, but I find it quite difficult to translate to Spanish or viceversa. Compounding things, the price of a good technical translating dictionary (in paper) is in the 100 Eur range. For english-german-english, you have advantage over me: there are good tools in linux. For spanish... ugh.
Anyhow, I would like to do some translation work for an open source project too, but then again, taking a look at a random man page frustrates more than anything: Even for a native English speaker, who is not exactly a Linux-buff though, the average man page is simply gibberish (try man mount, or - for the real brave - man rpm)
It is the technical side of how to edit a man page that still scares me.
And what helps a translation of an outdated or plain wrong documentation.
True enough. - -- Cheers, Carlos Robinson -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.0 (GNU/Linux) Comment: Made with pgp4pine 1.76 iD8DBQFETfyGtTMYHG2NR9URAmEQAJ49/29NuzTILM2e1FSH2O09+vfnjACfW+gd LPxHpzz7VOS4kw67TRbVgOA= =k8eu -----END PGP SIGNATURE-----
On Tue, Apr 25, 2006 at 12:40:04PM +0200, Carlos E. R. wrote:
It more difficult to translate than it seems. I can read, write, talk in English quite fluently, but I find it quite difficult to translate to Spanish or viceversa.
The same with me between English, German and Dutch. It is very hard for me to translate between these languages, _because_ I speak them so well. I think in each of the languages and for me it then is as if translationg between e.g. Dutch to Dutch. Oh well.
It is the technical side of how to edit a man page that still scares me.
What scares most developers is writing the thing in the first place. Also because the developer is so close, it is very hard to understand what a person sees and reads who has never used the program. e.g `makeSUSEdvd -a /usr/src/packages/RPMS` is obvious to me, but perhaps other people do not understand what I want with that or that subdirectories are also included and acturaly every file in that directory. Another thing you sometimes see in a man page is just a long list of parameters, but no examples or no good explanation. The manpage becomes nothing more then a copy of `program -h`. Nice to have once you know what you are doing, but hardly usefull if you are a fisrt time user of the program. houghi -- Nutze die Zeit. Sie ist das Kostbarste, was wir haben, denn es ist unwiederbringliche Lebenszeit. Leben ist aber mehr als Werk und Arbeit, und das Sein wichtiger als das Tun - Johannes Müller-Elmau
houghi wrote:
nothing more then a copy of `program -h`. Nice to have once you know what you are doing, but hardly usefull if you are a fisrt time user of the program.
but a man mapge is just that: a remainder of commands all other is a true documentation. you know the thing who lacks the more in big apps is the goal of the app. try to figure out what is the goal of Xen... jdd -- http://www.dodin.net http://dodin.org/galerie_photo_web/expo/index.html http://lucien.dodin.net http://fr.susewiki.org/index.php?title=Gérer_ses_photos
On Tue, Apr 25, 2006 at 03:02:59PM +0200, jdd wrote:
but a man mapge is just that: a remainder of commands
For me `an interface to the on-line reference manuals` is more then just a list of -v, -h, -l and so on.
all other is a true documentation.
OK. What should be at least added are some usable examples and more explanation then what the -h gives you. If you have that, then you have almost true documentation *for the use of the program*. Other documentation can talk about the history, the future, the people or worldpeace and should not be part of the manpage. One of the best manpages is, I think, fetchmail. Especially the part "CONFIGURATION EXAMPLES". I learned more from that chapter on how to use it then from any other part of the manpage. Once I had it running (did not took too long) I could look into the rest of the parameters and learn to use it.
you know the thing who lacks the more in big apps is the goal of the app.
try to figure out what is the goal of Xen...
Perhaps a mission and vision statement is more apropriate for large apps. ;-) houghi -- Nutze die Zeit. Sie ist das Kostbarste, was wir haben, denn es ist unwiederbringliche Lebenszeit. Leben ist aber mehr als Werk und Arbeit, und das Sein wichtiger als das Tun - Johannes Müller-Elmau
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 The Tuesday 2006-04-25 at 15:40 +0200, houghi wrote:
On Tue, Apr 25, 2006 at 03:02:59PM +0200, jdd wrote:
but a man mapge is just that: a remainder of commands
For me `an interface to the on-line reference manuals` is more then just a list of -v, -h, -l and so on.
For me, a man page is a manual: all information needed to use a program without need to read a paper manual. From the simple to the complex. If too complex, then use "info" pages instead, or added. It must include the syntax, some examples, and descriptions. If they don't like "info", then use html, but include an exact link in a small man page (some do this).
One of the best manpages is, I think, fetchmail. Especially the part "CONFIGURATION EXAMPLES". I learned more from that chapter on how to use it then from any other part of the manpage.
Another good one is "procmail", except that the examples are separated in "man procmailex". And a curious "-h" one is "smartctl": it gives examples. - -- Cheers, Carlos Robinson -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.0 (GNU/Linux) Comment: Made with pgp4pine 1.76 iD8DBQFETjjUtTMYHG2NR9URAhnXAJwPVKxgTT1IfSZm9HFZfZanPiat7gCggbKS 35WvZR5uxcmvy5Rg0IAjWrY= =P7tX -----END PGP SIGNATURE-----
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 The Tuesday 2006-04-25 at 14:47 +0200, houghi wrote:
On Tue, Apr 25, 2006 at 12:40:04PM +0200, Carlos E. R. wrote:
It more difficult to translate than it seems. I can read, write, talk in English quite fluently, but I find it quite difficult to translate to Spanish or viceversa.
The same with me between English, German and Dutch. It is very hard for me to translate between these languages, _because_ I speak them so well. I think in each of the languages and for me it then is as if translationg between e.g. Dutch to Dutch. Oh well.
Exactly :-)
Another thing you sometimes see in a man page is just a long list of parameters, but no examples or no good explanation. The manpage becomes nothing more then a copy of `program -h`. Nice to have once you know what you are doing, but hardly usefull if you are a fisrt time user of the program.
Very true! You have then to read all the man page, then study it, then decide how to use it... - -- Cheers, Carlos Robinson -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.0 (GNU/Linux) Comment: Made with pgp4pine 1.76 iD8DBQFETjdstTMYHG2NR9URAqbMAJ95RBoQb/IVTgydk9xgDrRTH07NYgCfaxPJ xavWjXpk0Wu6p/yzqR/PToI= =gYYh -----END PGP SIGNATURE-----
Carlos E. R. wrote:
Very true! You have then to read all the man page, then study it, then decide how to use it...
and at this moment it's time to make a wiki page; I do this most of the time not for the others but for myself, not to forget all... and I go to the wiki to find it again at will :-) jdd -- http://www.dodin.net http://dodin.org/galerie_photo_web/expo/index.html http://lucien.dodin.net http://fr.susewiki.org/index.php?title=Gérer_ses_photos
Am Montag, 24. April 2006 12:45 schrieb Carlos E. R.:
The Monday 2006-04-24 at 10:57 +0200, Henne Vogelsang wrote:
Help yourself. Get off _your_ butt and offer projects to write documentation :)
I'm collaborating in that respect (doing translations), but it is quite difficult to document a program you don't know what it does. Only the developpers can do that, I'm afraid. I can polish and expand a write up, but the first go has to be done by the developpers.
I used to work for a large consultancy, there the documentation was usually written by a special team of documentors, they had no programming knowledge, they took the finished (or sem-finished) programs, played with them and read the technical documentation and came up with user documentation from their experience, plus collaboration with the programming team for more technical areas. Usually developers and programmers are very good at writing specifications and writing code, but aren't as good at explaining it plain language for the non-computer literate, they tend to make too many assumptions or talk about the technicalities of the program and not on the normal use of the program... Don't get me wrong, some programmers can write good user documentation, but most haven't had the experience. Dave -- "I got to go figure," the tenant said. "We all got to figure. There's some way to stop this. It's not like lightning or earthquakes. We've got a bad thing made by men, and by God that's something we can change." - The Grapes of Wrath, by John Steinbeck
At 06:57 PM 24/04/2006, you wrote:
Hi,
On Sunday, April 23, 2006 at 19:05:41, scsijon wrote:
might just get some of these programmers off their buts and help us poor middle-users to understand their capabilities better.
Help yourself. Get off _your_ butt and offer projects to write documentation :)
Henne
love too! but, just where do I start; who's package has priority; how do i get the package (i'm on dialup only); what platforms versions will I need to hold; what is the testing schedule and who supplies the results so my documentation matches; what documentation level is needed; which documentation format standard is used; who supplies the "rough"; where are the templates; and so forth! And i'm not kidding, as i've just been told i'm to STOP working full time within three months or I will be dead within two years, no if's buts or maybe's. So, I'm busy talking to my clients and explaining/requesting contract changes. I expect to be offloading 95% of my Level 1 and 2 workload to others and will be only handling Level 3 support to them, only keeping a few local or "specials" at level 1 or 2. This means I expect that I will have about 3 hours a day available from July1. It also means a major earnings drop! back to you. scsijon
On Mon, Apr 24, 2006 at 09:02:58PM +1000, scsijon wrote:
but, just where do I start; who's package has priority; how do i get the package (i'm on dialup only); what platforms versions will I need to hold; what is the testing schedule and who supplies the results so my documentation matches; what documentation level is needed; which documentation format standard is used; who supplies the "rough"; where are the templates; and so forth!
These are all things you need to decide for yourself. You said that there were programs that lacked documentation. Start there. As you are on dialup, use a package that is available on your distro already. Start with a small program and contact the maintainer. Start with the README, then do the man pages. Later you can also do inline help. The person to contact is the developer itself. To know who that is, you can do the following in SUSE: 'pin program'. That should give you the emailadres of where to reach the maker of the program. houghi -- Nutze die Zeit. Sie ist das Kostbarste, was wir haben, denn es ist unwiederbringliche Lebenszeit. Leben ist aber mehr als Werk und Arbeit, und das Sein wichtiger als das Tun - Johannes Müller-Elmau
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 The Monday 2006-04-24 at 16:05 +0200, houghi wrote:
These are all things you need to decide for yourself. You said that there were programs that lacked documentation. Start there. As you are on dialup, use a package that is available on your distro already.
Impossible. You need the sources, and they are not included, you have to downloaded them. - -- Cheers, Carlos Robinson -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.0 (GNU/Linux) Comment: Made with pgp4pine 1.76 iD8DBQFETWERtTMYHG2NR9URAmiLAJ9CRpI+lVSBprQ0IijrisUx5MnUUwCfTRB1 b9AE9ukXqzApozX6QBvEdZg= =GQtf -----END PGP SIGNATURE-----
On Tue, Apr 25, 2006 at 01:36:32AM +0200, Carlos E. R. wrote:
The Monday 2006-04-24 at 16:05 +0200, houghi wrote:
These are all things you need to decide for yourself. You said that there were programs that lacked documentation. Start there. As you are on dialup, use a package that is available on your distro already.
Impossible. You need the sources, and they are not included, you have to downloaded them.
You only need the sources of the specific program you are working on. Well, I think that what you want is not available and the way you want it, not possible and this list not qualified. houghi -- Nutze die Zeit. Sie ist das Kostbarste, was wir haben, denn es ist unwiederbringliche Lebenszeit. Leben ist aber mehr als Werk und Arbeit, und das Sein wichtiger als das Tun - Johannes Müller-Elmau
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 The Tuesday 2006-04-25 at 01:53 +0200, houghi wrote:
These are all things you need to decide for yourself. You said that there were programs that lacked documentation. Start there. As you are on dialup, use a package that is available on your distro already.
Impossible. You need the sources, and they are not included, you have to downloaded them.
You only need the sources of the specific program you are working on.
Of course. But your recomendation of starting with a package included on the distro because he is on dial up, is not valid, because the sources are no longer included. That's what I meant. As a matter of fact, any one wanting to translate a project would better go to the project web page, and get the latest source. Then, he should contact the developpers, and this often means subscribing to the mailing list of that project (no single contact address provided or known). Sometimes he may need write access to the cvs server, and that is not so simple. It is a complicated thing, in fact. I know it, because I'm doing it.
Well, I think that what you want is not available and the way you want it, not possible and this list not qualified.
Why not? Wouldn't you like to improve linux and opensuse ? :-P - -- Cheers, Carlos Robinson -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.0 (GNU/Linux) Comment: Made with pgp4pine 1.76 iD8DBQFETWkVtTMYHG2NR9URApNRAJ9wo/slf0G7tu7ooct3X0kEVhFUeQCfUWM5 3GVR8PX6zErsqyNC6d4xDVc= =FG85 -----END PGP SIGNATURE-----
On Tue, Apr 25, 2006 at 02:10:59AM +0200, Carlos E. R. wrote:
You only need the sources of the specific program you are working on.
Of course. But your recomendation of starting with a package included on the distro because he is on dial up, is not valid, because the sources are no longer included. That's what I meant.
Not sure if you always need the sourcecode to work on documentation. But then that must be worked out with the developer.
Well, I think that what you want is not available and the way you want it, not possible and this list not qualified.
Why not? Wouldn't you like to improve linux and opensuse ? :-P
I am not saying it is not possible, I am saying it is not possible with what is asked and especialy the extra things added afterwards. Perhaps the questions needs to be reformulated with a clear objective and also clear explanation of what will not be possible. Many programs are just scripts and that still do not have very good documentation. Because they are just script, you have the sourcecode the moment you have the binary. That could already be a start. So what is the question and what are the limitations? It is clear that at this moment there is no one place of all Linux documentation for programs. houghi -- Nutze die Zeit. Sie ist das Kostbarste, was wir haben, denn es ist unwiederbringliche Lebenszeit. Leben ist aber mehr als Werk und Arbeit, und das Sein wichtiger als das Tun - Johannes Müller-Elmau
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 The Tuesday 2006-04-25 at 03:22 +0200, houghi wrote:
Not sure if you always need the sourcecode to work on documentation. But then that must be worked out with the developer.
You need the .po to generate the .pot files, and the gettext utilities. Also, you need the c source for context. Then, aside from the program itself, the plain doc is often not a plaintext, but is done with docbook or xml o some other thing you need the source of, not the end result we normally see.
So what is the question and what are the limitations? It is clear that at this moment there is no one place of all Linux documentation for programs.
True enough. - -- Cheers, Carlos Robinson -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.0 (GNU/Linux) Comment: Made with pgp4pine 1.76 iD8DBQFETgzktTMYHG2NR9URAtfBAJ0U2XQ6iz1dbtNn9pI75sIKXUlbAQCgkbzY Adm7mQxkHAvgOHpHWoAV25E= =wCay -----END PGP SIGNATURE-----
On Tue, Apr 25, 2006 at 01:48:49PM +0200, Carlos E. R. wrote:
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1
The Tuesday 2006-04-25 at 03:22 +0200, houghi wrote:
Not sure if you always need the sourcecode to work on documentation. But then that must be worked out with the developer.
You need the .po to generate the .pot files, and the gettext utilities. Also, you need the c source for context. Then, aside from the program itself, the plain doc is often not a plaintext, but is done with docbook or xml o some other thing you need the source of, not the end result we normally see.
See David Wright's reply about having seperate groups for Developers and Documenters. I also thought that .po files were for translation, not so much documentation. I will give an example of a very small script, makeSUSEdvd. There are no .po or .pot files. There are no things you need to compile, the script is the code. There is also no documaentation that comes with it. It points to a website. So writing documentation for that should be a not too difficult thing to do. There are many more scripts like that on SUSE that could use documentation and that are just scripts. Just do a `for I in /usr/bin/*;do file $I|grep script;done` and then start looking for scripts that do not have good documentation. You have your sourcecode right there. With pin you are able to contact the developers. And with the above, you just find those that are inslalled on your system and in /usr/bin. There are more places to find things. houghi -- Nutze die Zeit. Sie ist das Kostbarste, was wir haben, denn es ist unwiederbringliche Lebenszeit. Leben ist aber mehr als Werk und Arbeit, und das Sein wichtiger als das Tun - Johannes Müller-Elmau
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 The Tuesday 2006-04-25 at 15:05 +0200, houghi wrote:
You need the .po to generate the .pot files, and the gettext utilities. Also, you need the c source for context. Then, aside from the program itself, the plain doc is often not a plaintext, but is done with docbook or xml o some other thing you need the source of, not the end result we normally see.
See David Wright's reply about having seperate groups for Developers and Documenters. I also thought that .po files were for translation, not so much documentation.
Right, they are needed for translation. My point is that you need the sources for translations of programs and anexed documentations.
I will give an example of a very small script, makeSUSEdvd. There are no .po or .pot files. There are no things you need to compile, the script is the code. There is also no documaentation that comes with it. It points to a website.
Of course, that's true. I don't know if it is possible to "internationallise" an script, ie, translate its messages.
So writing documentation for that should be a not too difficult thing to do.
Often in SuSE scripts are self-documented, with comments. It would be very dificult to maintain that kind of documentation in diferent languages. In those cases, the translation has to be separate.
There are many more scripts like that on SUSE that could use documentation and that are just scripts. Just do a `for I in /usr/bin/*;do file $I|grep script;done` and then start looking for scripts that do not have good documentation.
SpamAssassin and amavis-new are very much needed of user documentation. You need to read the "source code" in the configuration file. - -- Cheers, Carlos Robinson -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.0 (GNU/Linux) Comment: Made with pgp4pine 1.76 iD8DBQFETjtvtTMYHG2NR9URAhiDAJ9jh4gIouzmd7Y2a0IWyCZB3ejWhQCePei/ VlZGI96inh94mfgItofJ4mw= =vgbK -----END PGP SIGNATURE-----
On Tue, Apr 25, 2006 at 05:08:29PM +0200, Carlos E. R. wrote:
Of course, that's true. I don't know if it is possible to "internationallise" an script, ie, translate its messages.
Sure it is. Check the language settings and then do with that what you like. Either in the script or outside of it. MY_LANG=`locale|grep LANG|awk -F= '{print $NF}'` Then use: en_US_MESSAGE1="This is message 1" nl_BE_MESSAGE1="Dit is bericht 1" ... For the real message you can then use: echo "${MY_LANG}_MESSAGE1" You can even make it easier and use MESSAGE1=${MY_LANG}_MESSAGE1 You will need some extra testing, go back to a default and so on, but in general it is not that hard to do. Using an external file might be easier: MY_LANG=`locale|grep LANG|awk -F= '{print $NF}'` then use . ${MY_LANG}.po There you have en_US.po : MESSAGE1="This is message 1" nl_BE.po : MESSAGE1="Dit is bericht 1" In the script you then use: echo $MESSAGE1 I am sure other people will have much better solutions. It is just a prove of concept.
Often in SuSE scripts are self-documented, with comments. It would be very dificult to maintain that kind of documentation in diferent languages. In those cases, the translation has to be separate.
Those are remarks, not so much documentation. I am talking about documentation for the user. You are talking about documentation for the developer. Again an whole other issue. Please stop sidestepping the issue. This is as far as I can see how the discussion is going: + I would like to have better user documentation - Write it + Well, actually I would like user documents translations - Well, translate it + Well, actually I would developer comments translated ... So again please rephrase what you want and what you do not want. houghi -- Nutze die Zeit. Sie ist das Kostbarste, was wir haben, denn es ist unwiederbringliche Lebenszeit. Leben ist aber mehr als Werk und Arbeit, und das Sein wichtiger als das Tun - Johannes Müller-Elmau
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 The Tuesday 2006-04-25 at 17:40 +0200, houghi wrote:
On Tue, Apr 25, 2006 at 05:08:29PM +0200, Carlos E. R. wrote:
Of course, that's true. I don't know if it is possible to "internationallise" an script, ie, translate its messages.
Sure it is. Check the language settings and then do with that what you like. Either in the script or outside of it. ... I am sure other people will have much better solutions. It is just a prove of concept.
Ok. But it needs a programming effort. It doesn't use the GNU gettext utilities. In fact, I don't think I have seen a bash script with translations: it must be difficult.
Often in SuSE scripts are self-documented, with comments. It would be very dificult to maintain that kind of documentation in diferent languages. In those cases, the translation has to be separate.
Those are remarks, not so much documentation. I am talking about documentation for the user. You are talking about documentation for the developer. Again an whole other issue.
Please stop sidestepping the issue.
Hey, notice that there are several people in this thread, and each one looks at the issue differently. I'm interested mostly in translation. I'm also interested in documentation, in general, but I'll try to keep my self mostly centered in translation: of the program and of the documentation. There are scripts, like amavis-new, that do not have documentation included in the rpm. If you ask, they say that "the configuration file is self documented, jut read it". I fully agree that it is documentation for the developer, but that is what there is. I said that as an example of the difficulties.
This is as far as I can see how the discussion is going: + I would like to have better user documentation - Write it + Well, actually I would like user documents translations - Well, translate it + Well, actually I would developer comments translated
I certainly do not want the comments translated. I'm just asking how you document in different languages something that does not have separate documentation; if they point you to read the comments included in the script, instead of having a real users documentation.
...
So again please rephrase what you want and what you do not want.
You are misunderstanding me. And remember, please, that at the moment I'm currently translating a biggish program to Spanish. This is not idle talk on my part. - -- Cheers, Carlos Robinson -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.0 (GNU/Linux) Comment: Made with pgp4pine 1.76 iD8DBQFETmVrtTMYHG2NR9URAqCEAJ0Tb8qaEtV7ZjQxWokBPMMpERYBmACdHx0t WbjsqfxR+tQr4qC8d7EBDyE= =gwsn -----END PGP SIGNATURE-----
On Tue, Apr 25, 2006 at 08:07:38PM +0200, Carlos E. R. wrote:
Ok. But it needs a programming effort. It doesn't use the GNU gettext utilities. In fact, I don't think I have seen a bash script with translations: it must be difficult.
It is not difficult, it just is not worth the extra trouble. It would double or tripple the size of your script and make it more complicated then needed. It also doe NOT need programming efford enymore then a .po file does. The fact that it does not use gettext utilities is also of no importance. It can be done reasonably easy. It is just not worth the efford. 81 lines from the 610 in makeSUSEdvd contain 'echo' wich means that is the number of lines I would have to edit. For each language, either the script will be 81 lines longer, or the download more complex. I am sure people can make a working script that says 'Uw taal is' or 'Your language is' or whatever in under 20 lines.
Hey, notice that there are several people in this thread, and each one looks at the issue differently. I'm interested mostly in translation. I'm also interested in documentation, in general, but I'll try to keep my self mostly centered in translation: of the program and of the documentation.
Sorry, mixed you up with the OP. houghi -- Nutze die Zeit. Sie ist das Kostbarste, was wir haben, denn es ist unwiederbringliche Lebenszeit. Leben ist aber mehr als Werk und Arbeit, und das Sein wichtiger als das Tun - Johannes Müller-Elmau
Am Dienstag, 25. April 2006 01:36 schrieb Carlos E. R.:
The Monday 2006-04-24 at 16:05 +0200, houghi wrote:
These are all things you need to decide for yourself. You said that there were programs that lacked documentation. Start there. As you are on dialup, use a package that is available on your distro already.
Impossible. You need the sources, and they are not included, you have to downloaded them.
You should write the documentation from the original specifications, not from the source code, same as writing test harnesses and test scripts. If you write from the specification, you are documenting what the program *should* do, which acts as a good double check that the code is doing what *it* should. Most of the professional documentors I've worked with wouldn't have a clue where to start if you gave them source code, but give them an executable to play with and a RUP, CACI etc. standard specification and they are happy little bees and will knock up documentation in no time... Dave -- "I got to go figure," the tenant said. "We all got to figure. There's some way to stop this. It's not like lightning or earthquakes. We've got a bad thing made by men, and by God that's something we can change." - The Grapes of Wrath, by John Steinbeck
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 The Tuesday 2006-04-25 at 12:09 +0200, David Wright wrote:
Impossible. You need the sources, and they are not included, you have to downloaded them.
You should write the documentation from the original specifications, not from the source code, same as writing test harnesses and test scripts. If you write from the specification, you are documenting what the program *should* do, which acts as a good double check that the code is doing what *it* should.
No, I don't mean that. To translate a program you need the sources because the documentation you see is the output of a postprocess. You need the sources of the documentation. Also, for the step of translating the messages a program gives you do need the source code. In theory, the .po file should be enough, but you need the context. - -- Cheers, Carlos Robinson -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.0 (GNU/Linux) Comment: Made with pgp4pine 1.76 iD8DBQFETf27tTMYHG2NR9URAktfAJ92nvlDbWpDKX38c6mtNhdBCX5jPgCfYnoK pVYx5KpucOLeOKE3udgCw54= =6hE8 -----END PGP SIGNATURE-----
On Tue, Apr 25, 2006 at 12:45:13PM +0200, Carlos E. R. wrote:
To translate a program you need the sources because the documentation you see is the output of a postprocess. You need the sources of the documentation. Also, for the step of translating the messages a program gives you do need the source code. In theory, the .po file should be enough, but you need the context.
And here I thought it was about documentation. Now suddenly it is about translating programs. Writing Documentation and even translating Documentation is something different then translating a program. A running program should be enough to translate your .po file. However it could then indeed be that some sourcecode editing is needed. This was not what I thought we were talking about. I understood that we were talking about documentation of a program. Now that it looks we are talking about translation of a program, so it can be used in multiple languages natively, everything that has been said means nothing, as we were talking about different things. houghi -- Nutze die Zeit. Sie ist das Kostbarste, was wir haben, denn es ist unwiederbringliche Lebenszeit. Leben ist aber mehr als Werk und Arbeit, und das Sein wichtiger als das Tun - Johannes Müller-Elmau
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 The Tuesday 2006-04-25 at 15:12 +0200, houghi wrote:
And here I thought it was about documentation. Now suddenly it is about translating programs. Writing Documentation and even translating Documentation is something different then translating a program.
I was talking about both things, because for me they are related. For many people the non existence of a translation means there is no documentation at all! So they go to the list and ask you absurd questions that are explained first thing in the documentation, and I can not tell them to RTFM because they can't :-(
A running program should be enough to translate your .po file. However it could then indeed be that some sourcecode editing is needed.
No, no, that should not be needed. If that is the case, you have to tell the developpers. I meant that we have to look sometimes at the source code to get the context and meaning of isolated sentences, but I don't even try to touch the code. Some times the code has comments that clarify things.
This was not what I thought we were talking about. I understood that we were talking about documentation of a program. Now that it looks we are talking about translation of a program, so it can be used in multiple languages natively, everything that has been said means nothing, as we were talking about different things.
Sorry about the confussion. In my messages I talked about both things, perhaps you didn't notice. - -- Cheers, Carlos Robinson -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.0 (GNU/Linux) Comment: Made with pgp4pine 1.76 iD8DBQFETj0wtTMYHG2NR9URAuFuAJ9g7m6OLADMR2pfIqgSz78tJ7eBrwCbBVcq GpoSs7PtlElEzpkt3MskfnI= =mxPT -----END PGP SIGNATURE-----
participants (8)
-
Andreas -
Carlos E. R. -
David Wright -
Henne Vogelsang -
Henne Vogelsang -
houghi -
jdd -
scsijon