[opensuse] Where is the perl documentation on OpenSuse 12.3
The subject says it all. I have searched my suse box top to bottom, as it where, and I can not find the perl documentation. Mind you, that may be a consequence of still trying to master OpenSuse. I am using cpan to get modules, but I regularly consult the documentation for the modules, especially those modules that are large and complex. The was easy on my old Windows machine, as ActiveState's installer put an icon pointing to the index for the HTML version of the documentation. And on my Ubuntu machine, there is an icon attached to the bar on the left pointing to the pod browser (though it seems not all the modules have documentation in pod format - either that or they are not found by the pod browser). But, on my opensuse box (running suse 12.3) I can't find any perl documentation. Can anyone tell me where it is? Thanks Ted -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
On 13-12-17 06:30 PM, Anton Aylward wrote:
Ted Byers said the following on 12/17/2013 06:02 PM:
[...] Can anyone tell me where it is?
Does this command return anything?
$ apropos perl
Hi Anton, Thanks for this. Yes. I get basically a list of perl modules that have been installed. What is apropos? I never heard of that before. It is great that apropos lists all these perl modules, but what is the next step to actually be able to browse the documentation? Thanks Ted -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
On 12/17/2013 3:42 PM, Ted Byers wrote:
but what is the next step to actually be able to browse the documentation?
Start here: http://perldoc.perl.org/ If you don't want to browse online there are links at the bottom of that page for downloading the full set in either html form or PDF. -- _____________________________________ ---This space for rent--- -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
On 13-12-17 06:51 PM, John Andersen wrote:
On 12/17/2013 3:42 PM, Ted Byers wrote:
but what is the next step to actually be able to browse the documentation? Start here: http://perldoc.perl.org/
If you don't want to browse online there are links at the bottom of that page for downloading the full set in either html form or PDF.
Thanks John, The is the documentation for the core modules, right? What about the modules I install using cpan? Thanks Ted -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
On Tue, Dec 17, 2013 at 03:51:05PM -0800, John Andersen wrote:
On 12/17/2013 3:42 PM, Ted Byers wrote:
but what is the next step to actually be able to browse the documentation?
Start here: http://perldoc.perl.org/
If you don't want to browse online there are links at the bottom of that page for downloading the full set in either html form or PDF.
an alternate way to get it is to go into System -> Yast (Control Center) -> Software Management enter a Search arg of perl, then scroll and scroll and scroll until you get to perl-doc -- it will be for the same version of perl you have, and if you watch the install you should be able to find where it goes hth -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
On 13-12-17 07:33 PM, tooth pik wrote:
On Tue, Dec 17, 2013 at 03:51:05PM -0800, John Andersen wrote:
On 12/17/2013 3:42 PM, Ted Byers wrote:
but what is the next step to actually be able to browse the documentation? Start here: http://perldoc.perl.org/ If you don't want to browse online there are links at the bottom of that page for downloading the full set in either html form or PDF. an alternate way to get it is to go into System -> Yast (Control Center) -> Software Management
enter a Search arg of perl, then scroll and scroll and scroll until you get to perl-doc -- it will be for the same version of perl you have, and if you watch the install you should be able to find where it goes
hth Hi Mr pik,
Thanks, that does help. it appears to all be in /usr/lib/perl/pod. But that begs the question, how do I view it all. Is there a program that provides an index to it all, and lets me just select the packages whose documentation I want to review, and that without losing the index (or an easy way to get back to it). Multiple windows showing different parts of the docs would be quite useful, because I often need to look at how two or more modules can be used together. With HTML docs, I do that with Firefox, but Firefox tends to become a memory hog when you have a lot of pages open. Thanks, Ted -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
On 12/17/2013 5:14 PM, Ted Byers wrote:
Thanks, that does help. it appears to all be in /usr/lib/perl/pod. But that begs the question, how do I view it all.
To get the documentation of any module type perldoc (command) in a shell. For instance to see the documentation of IO::File type perldoc IO::File If you install all the documentation it should have all you need. If you need multiple pages open at once open a new shell, (or a new tab in Konsole) an type As to worrying about firefox taking memory, what else were you planning to do with that memory while editing perl scripts? Dont worry about the memory, its your computer, use it. Use all of it. Every last byte. But DO start reading on this page: http://www.perl.org/docs.html It tells about how to use perldoc, several alternate sources for documentation of modules, alpha index to core modules, Code examples, etc. -- _____________________________________ ---This space for rent--- -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
On 13-12-17 08:31 PM, John Andersen wrote:
Thanks, that does help. it appears to all be in /usr/lib/perl/pod. But that begs the question, how do I view it all. To get the documentation of any module type
On 12/17/2013 5:14 PM, Ted Byers wrote: perldoc (command) in a shell. Thanks. perldoc seems to be a perl equivalent of man. It is serviceable. It isn't ideal as there is no index that can be used to load the documentation for one of the installed modules.
For instance to see the documentation of IO::File type perldoc IO::File
If you install all the documentation it should have all you need. If you need multiple pages open at once open a new shell, (or a new tab in Konsole) an type I suppose it is safe to assume that if I tell cpan to install a given module, the documentation for that module will also be installed.
I can work with this.
As to worrying about firefox taking memory, what else were you planning to do with that memory while editing perl scripts? Dont worry about the memory, its your computer, use it. Use all of it. Every last byte.
I only start worrying about memory when it becomes so exploited that the machine starts to slow down; or when Firefox starts to crash because it can't handle so much data (or, more likely, the memory allocated to handling so many windows being open).
But DO start reading on this page: http://www.perl.org/docs.html It tells about how to use perldoc, several alternate sources for documentation of modules, alpha index to core modules, Code examples, etc.
OK, that is on the todo list for tomorrow, especially the alpha index. I'll be doing some exploring to find a useful index. Thanks Ted -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
Ted Byers said the following on 12/17/2013 09:07 PM:
On 13-12-17 08:31 PM, John Andersen wrote:
Thanks, that does help. it appears to all be in /usr/lib/perl/pod. But that begs the question, how do I view it all. To get the documentation of any module type
On 12/17/2013 5:14 PM, Ted Byers wrote: perldoc (command) in a shell. Thanks. perldoc seems to be a perl equivalent of man. It is serviceable. It isn't ideal as there is no index that can be used to load the documentation for one of the installed modules.
There isn't a index of the man pages either, you have to build it. Its done every night -- it used to be done by mkwhatis, but we're in the 21st century now. Take a look in /etc/cron.daily/suse-do_mandb If you add another location you'll have to add it to /etc/manpath.config and either have it recognise .pod and do the conversion on the fly so man(1) and view it, or batch convert the .pod files. I'd go for the latter. Oh, and add the location of all that to appropriate places in /etc/manpath.config so that they get included in the index. That way its all covered by the MAN command and you don't have to worry if some things are dealt by perlpod and some by man -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
Hello, First of all, the OP should install the 'perl-doc' package. It alone contains the basic perl documentation of over 1000 files (including 810 manpages here). On Tue, 17 Dec 2013, Anton Aylward wrote: [..]
There isn't a index of the man pages either, you have to build it. Its done every night -- it used to be done by mkwhatis, but we're in the 21st century now. Take a look in /etc/cron.daily/suse-do_mandb
Those dbs are what apropos/man -k use. And what would you call those but an "index" of man pages? And mandb and that cronjob are part of the man package ...
That way its all covered by the MAN command and you don't have to worry if some things are dealt by perlpod and some by man
I've been using SuSE since 5.3, many times with modules from CPAN or even self-written ones, a self-compiled and not rpm-packaged perl, and thanks to pod2man there was *always* a man Foo::Bar for any module "Foo::Bar". The only exception to that rule is: man -k perl | grep ^perl That even is valid for pragmas, see 'man 3pm strict' or 'man 3pm warnings'. And your "index" goes like this: man -k . -s 3pm for which I currently get a mere 6599 entries ... (BTW: option order matters in this case: $ man -k . -s 3pm | wc -l 6599 $ man -s 3pm -k . | wc -l 33192 the latter listing all manpages or so it seems at a first glance and $ rpm -qal | grep -c /usr/share/man 32640 seems to agree as I do have some (e.g. perl) stuff not packaged as an rpm installed). Lack of documentation? There are some perl-programs in section 1 (e.g. "frozen-bubble") and probably some modules in section 3 (instead of 3pm). And for the index the op searched, how about konqueror's "man:" io-slave, just enter 'man:(3p)' into konqueror's adress bar for the index of perl documentation (well, the konq from 3.5.10 and 4.7 are both broken and list all manpages in section 3 even if specifying 3pm). But well, it's a HTML-like index of manpages ;) And then there's e.g. tkman. But do NOT forget about perldoc. Its -q, -f and -v options are extremely useful, c.f. e.g.: perldoc -v '$/' even though you could read up on that stuff in man perlfaq* perlvar perlfunc, perldoc's function is much more pratical. But generally man is faster than perldoc. -dnh, documentation fetishist -- Memory fault -- core...uh...um...core... Oh dammit, I forget! -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
David Haller said the following on 12/17/2013 11:42 PM:
Lack of documentation? There are some perl-programs in section 1 (e.g. "frozen-bubble") and probably some modules in section 3 (instead of 3pm).
And for the index the op searched, how about konqueror's "man:" io-slave, just enter 'man:(3p)' into konqueror's adress bar for the index of perl documentation (well, the konq from 3.5.10 and 4.7 are both broken and list all manpages in section 3 even if specifying 3pm). But well, it's a HTML-like index of manpages;)
And then there's e.g. tkman.
But do NOT forget about perldoc. Its -q, -f and -v options are extremely useful, c.f. e.g.: perldoc -v '$/' even though you could read up on that stuff in man perlfaq* perlvar perlfunc, perldoc's function is much more pratical. But generally man is faster than perldoc.
-dnh, documentation fetishist
I come from Aviation where documentation is an obsession that exceeds even that I encountered in the military and government. I recognise all that 'perldoc' can do. No criticisms there. But I also see that all the permutations of using MAN you describe are about what is available under "MAN". And that is the point I was trying to make. KISS as one command and not having to do lots of options because it is all set up in /etc/manpath.config and the environment variable. Yes you are right when you point out that the tools that build the the MAN index db come with the package. But those tools make use of what is in /etc/manpath.config. If a user adds new stuff ... ~/mydevelopmentsprojects/man ... then that needs to be added so that it gets indexed. Not different with perl documentation. By default MAN91) wants things in man/troff format, so ether convert, or supply the information to convert-on-the-fly using pos2man. I don't want to have different things for different apps, I want consistency. I want 'apropos' and 'man' to work with everything. I don't want to try using 'man', have it fail, then wonder if I should use 'perlpod'. There is the presumption implicit in that each language should have its own tools for doing documentation, that C code uses 'man', that there is another for shell scripts even if they are in /usr/bin, another for perl scripts so that 'man spamassassin' would not work but 'perlpod Mail::SpamAssassin' would. And so forth for awk, python and all the rest. Well $OBSCENITY that! Please note, that the cognitive load even of that example when dealing with "Mail::SpamAssassin" needs to the modules group -- "Mail" and that module name is in CamelCase. Compare with the simplicity of the MAN(1) version. There's nothing wrong with using perlpod. There's also noting wrong with using perl one-liners or shell one liners on the command line instead of scripts. maybe they are just use-once-and-throw-away. But I'd rather the Old Unix Way of having a general tool and its 'smarts' in a config file that having a lot of different, language specific ways of reading the documentation. Maybe I'm lazy. Maybe I'm 'A bear of Little brain and long-winded ways of doing things confuse me'. Maybe I believe in KISS. personally I like using apropos, as I've said many times. Using LOCATE(1) is good as well :-) Running "locate '*.pod'" would have answered the OPs original question as to the "WHERE", but not about how to read the documentation. Ah, and while 'man pod2man' returned nothing, 'locate pod2man' told me that the program was in /usr/bin. The "file ($locate pod2man)" tells me its a perl script and 'pod2man --help' produces the POD in man page format. If I want that accessible to MAN(1) I better use "pod2man $(locate pod2man)" and put the result in the man page hierarchy, possibly in the part I've reserved for pod-conversions :-) and entered in /etc/manpath.config. Then when 'mkwhatis' runs tonight, it will get indexed and 'man pod2man' will now work. Of course I can also run "file /usr/bin/* | grep 'Perl script'" to see what else is there and see what else doesn't already have a MAN page. Although since not every perl script will have embedded POD, perhaps this is a better way of finding those that do and are candidates for 'pod2man': grep -l "=head1" /usr/bin/* -- Better be despised for too anxious apprehensions, than ruined by too confident security. -- Edmund Burke -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
On 12/18/2013 5:09 AM, Anton Aylward wrote:
David Haller said the following on 12/17/2013 11:42 PM:
Lack of documentation? There are some perl-programs in section 1 (e.g. "frozen-bubble") and probably some modules in section 3 (instead of 3pm).
And for the index the op searched, how about konqueror's "man:" io-slave, just enter 'man:(3p)' into konqueror's adress bar for the index of perl documentation (well, the konq from 3.5.10 and 4.7 are both broken and list all manpages in section 3 even if specifying 3pm). But well, it's a HTML-like index of manpages;)
And then there's e.g. tkman.
But do NOT forget about perldoc. Its -q, -f and -v options are extremely useful, c.f. e.g.: perldoc -v '$/' even though you could read up on that stuff in man perlfaq* perlvar perlfunc, perldoc's function is much more pratical. But generally man is faster than perldoc.
-dnh, documentation fetishist
I come from Aviation where documentation is an obsession that exceeds even that I encountered in the military and government.
I recognise all that 'perldoc' can do. No criticisms there.
But I also see that all the permutations of using MAN you describe are about what is available under "MAN". And that is the point I was trying to make. KISS as one command and not having to do lots of options because it is all set up in /etc/manpath.config and the environment variable.
Yes you are right when you point out that the tools that build the the MAN index db come with the package. But those tools make use of what is in /etc/manpath.config. If a user adds new stuff ... ~/mydevelopmentsprojects/man ... then that needs to be added so that it gets indexed. Not different with perl documentation. By default MAN91) wants things in man/troff format, so ether convert, or supply the information to convert-on-the-fly using pos2man.
I don't want to have different things for different apps, I want consistency. I want 'apropos' and 'man' to work with everything. I don't want to try using 'man', have it fail, then wonder if I should use 'perlpod'. There is the presumption implicit in that each language should have its own tools for doing documentation, that C code uses 'man', that there is another for shell scripts even if they are in /usr/bin, another for perl scripts so that 'man spamassassin' would not work but 'perlpod Mail::SpamAssassin' would. And so forth for awk, python and all the rest.
Well $OBSCENITY that!
Please note, that the cognitive load even of that example when dealing with "Mail::SpamAssassin" needs to the modules group -- "Mail" and that module name is in CamelCase. Compare with the simplicity of the MAN(1) version.
There's nothing wrong with using perlpod. There's also noting wrong with using perl one-liners or shell one liners on the command line instead of scripts. maybe they are just use-once-and-throw-away. But I'd rather the Old Unix Way of having a general tool and its 'smarts' in a config file that having a lot of different, language specific ways of reading the documentation.
Maybe I'm lazy. Maybe I'm 'A bear of Little brain and long-winded ways of doing things confuse me'. Maybe I believe in KISS.
personally I like using apropos, as I've said many times. Using LOCATE(1) is good as well :-) Running "locate '*.pod'" would have answered the OPs original question as to the "WHERE", but not about how to read the documentation.
Ah, and while 'man pod2man' returned nothing, 'locate pod2man' told me that the program was in /usr/bin. The "file ($locate pod2man)" tells me its a perl script and 'pod2man --help' produces the POD in man page format. If I want that accessible to MAN(1) I better use "pod2man $(locate pod2man)" and put the result in the man page hierarchy, possibly in the part I've reserved for pod-conversions :-) and entered in /etc/manpath.config. Then when 'mkwhatis' runs tonight, it will get indexed and 'man pod2man' will now work.
Of course I can also run "file /usr/bin/* | grep 'Perl script'" to see what else is there and see what else doesn't already have a MAN page. Although since not every perl script will have embedded POD, perhaps this is a better way of finding those that do and are candidates for 'pod2man':
grep -l "=head1" /usr/bin/*
Was there a question in there, or were you just venting? There are a multitude of tools, and if you prefer ONE and only ONE tool, then I suggest your best bet is a web browser. With any half way decent internet connection Google will find your answer faster than digging around on your own machine. -- _____________________________________ ---This space for rent--- -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
Anton Aylward wrote:
Yes you are right when you point out that the tools that build the the MAN index db come with the package. But those tools make use of what is in /etc/manpath.config. If a user adds new stuff ... ~/mydevelopmentsprojects/man ... then that needs to be added so that it gets indexed. Not different with perl documentation. By default MAN91) wants things in man/troff format, so ether convert, or supply the information to convert-on-the-fly using pos2man.
MAN91 should also recognize things in cat
I don't want to have different things for different apps, I want consistency. I want 'apropos' and 'man' to work with everything.
---- AFAIK, they do.
Please note, that the cognitive load even of that example when dealing with "Mail::SpamAssassin" needs to the modules group -- "Mail" and that module name is in CamelCase. Compare with the simplicity of the MAN(1) version.
I agree w/that!... but note: having "man" ignore case is a suse 'extension' that isn't on every platform.
Ah, and while 'man pod2man' returned nothing,
Then you do not have perl-doc 5.16 nor 5.18 installed: rpm -ql perl-doc|grep pod2man /usr/share/man/man1/pod2man.1.gz
Then when 'mkwhatis' runs tonight, it will get indexed and 'man pod2man' will now work.
Wouldn't just installing the perl-doc package be better?
Of course I can also run "file /usr/bin/* | grep 'Perl script'" to see what else is there and see what else doesn't already have a MAN page. Although since not every perl script will have embedded POD, perhaps this is a better way of finding those that do and are candidates for 'pod2man':
grep -l "=head1" /usr/bin/*
---- Most should have their own man page... If they don't, it's likely a bug or oversight. -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
Linda Walsh said the following on 12/18/2013 03:37 PM:
Please note, that the cognitive load even of that example when dealing with "Mail::SpamAssassin" needs to the modules group -- "Mail" and that module name is in CamelCase. Compare with the simplicity of the MAN(1) version.
I agree w/that!... but note: having "man" ignore case is a suse 'extension' that isn't on every platform.
Oh really? I seem to recall it ignoring case on UNIX V7, SYSIII, SYSV, SCO UNIX and others. Which distribution were you thinking of? OBTW, Linda. I subscribe to the list. There is no need to cc me when posting to the list. -- Never try to reason the prejudice out of a man. It was not reasoned into him, and cannot be reasoned out. Sydney Smith -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
Anton Aylward wrote:
Linda Walsh said the following on 12/18/2013 03:37 PM:
Please note, that the cognitive load even of that example when dealing with "Mail::SpamAssassin" needs to the modules group -- "Mail" and that module name is in CamelCase. Compare with the simplicity of the MAN(1) version.
I agree w/that!... but note: having "man" ignore case is a suse 'extension' that isn't on every platform.
Oh really? I seem to recall it ignoring case on UNIX V7, SYSIII, SYSV, SCO UNIX and others.
Which distribution were you thinking of?
Looking further, it seems it is a SYSV extension... and that BSD derived man is the exception. So I see a bug for MacOS @ http://rt.openssl.org/Ticket/Display.html?id=2820&user=guest&pass=guest that talks about case insensitivity on MacOS, I see it as a question here: http://unix.stackexchange.com/questions/101295/case-insensitive-search-in-ma... And I know it to be the default case on the man program used by 'Cygwin' (appears to be BSD derived). Unfortunately, the BSD acolytes have been working @ POSIX to change various POSIX commands to reflect the BSD quirks. Since there aren't any companies representing the SYSV standard anymore, they find they can push through changes that were met w/resistance before. (Like changing POSIX to be proscriptive (mandating), rather than "descriptive" as it was up to ~2001. Example: used to be you could remove everything UNDER a directory and limit it to the current file system with "rm -fr --one-filesystem DIR/." That functionality was removed to conform with BSD practice to check for "." out-of-sequence in "rm" (i.e. when you do a "rm -fr", it is a depth-first traversal but POSIX dictates that each path component be inspected before traversing it's contents for "." or ".." and fail immediately if it finds such. It used to be that it gave a suppressible error message (-f suppressed the message).
OBTW, Linda. I subscribe to the list. There is no need to cc me when posting to the list.
--- Hey, you have your own domain Anton, surely you know that it is your email application that is directing me to post a copy to you and to the list when I hit reply all. If you setup your email program to insert a reply-to: <listname>, then replies will only be sent to the list. If you don't do that, you are asking for a personal reply when the responder hits "reply" or "reply all". Some modern email programs also provide a non-standard "reply to list" option, but that hasn't made it into the standards yet, that I am aware of... ---- BTW, you didn't mention how you missed having the perl-doc manpages installed but were "going off" on how various perl-related commands didn't have man pages? ;-) -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
Linda Walsh said the following on 12/18/2013 04:45 PM:
Hey, you have your own domain Anton, surely you know that it is your email application that is directing me to post a copy to you and to the list when I hit reply all.
If you setup your email program to insert a reply-to: <listname>, then replies will only be sent to the list. If you don't do that, you are asking for a personal reply when the responder hits "reply" or "reply all".
You really don't want me filling in the 'Reply-to" fields. Believe me, you don't! And anyway, I suggest you go back to the archives and review the past discussion we've had about 'reply-to'. I'm just following what the list managers recommend. You're the one who is being deviant on this matter. -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
On 12/18/2013 05:38 PM, Anton Aylward pecked at the keyboard and wrote:
Linda Walsh said the following on 12/18/2013 04:45 PM:
Hey, you have your own domain Anton, surely you know that it is your email application that is directing me to post a copy to you and to the list when I hit reply all.
If you setup your email program to insert a reply-to: <listname>, then replies will only be sent to the list. If you don't do that, you are asking for a personal reply when the responder hits "reply" or "reply all".
You really don't want me filling in the 'Reply-to" fields. Believe me, you don't!
And anyway, I suggest you go back to the archives and review the past discussion we've had about 'reply-to'. I'm just following what the list managers recommend. You're the one who is being deviant on this matter.
People are just better off creating a filter so all of Linda's posts go directly to trash. She will remain defiant to the end and never accept the fact that the openSUSE lists are properly setup. -- Ken Schneider SuSe since Version 5.2, June 1998 -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
Ken Schneider - openSUSE wrote:
People are just better off creating a filter so all of Linda's posts go directly to trash. She will remain defiant to the end and never accept the fact that the openSUSE lists are properly setup.
In no way to I claim the lists are improperly setup. I do claim that compliant mail agents will respond to all when asked to. If the source agent of an email puts in a "reply-to" field, it is also compliant to use that field. I get multiple copies from some people and get single copies from others. If someone is directing an email at me, they will have the courtesy to make sure I'm in the To or Cc list, or I might miss it. It is not uncommon to filter email into personal and list email. Email that is addressed to the person (in addition to a list) will goto their personal folders, whereas email to a list will go to a list folder. I could just as easily filter email that comes to me *and a list*, into the bit-bucket as not needed, IF it bothered me so much as to complain to a list about it. But some people think that complaining to a list (about something they can solve themselves), is productive. Go figger. I much prefer to rely on myself than attempt to shame or coerce others into behaving a certain way....that's why I prefer to have options and prefer offering options that allow them to have what they want on their machine while I have what I want on mine. Works out well that way... -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
Linda Walsh said the following on 12/18/2013 04:45 PM:
Hey, you have your own domain Anton, surely you know that it is your email application that is directing me to post a copy to you and to the list when I hit reply all.
Linda, I am not mailing you personally; I am mailing the list. I use 'reply-to-list. I have a modern (intelligent) mail user agent. Replying to both the list and me (using 'reply-all') is redundant and if your mailer doesn't have a reply-to-list then either you are being perverse or you are not using an up to date browser or you are simply being lazy in using 'reply-all' and not deleting addresses that aren't the list. As I said, I am not mailing you directly. I am making use of mailing list management software which is acting as a publisher. The publisher, the list manage software is taking care of the headers being RFC-2369 compliant. That your mail software can't recognise the "List-post:" header and offer you a 'reply to list' option means that this is your problem not mine. -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
Anton Aylward wrote:
Linda, I am not mailing you personally; I am mailing the list. I use 'reply-to-list. I have a modern (intelligent) mail user agent.
recognise the "List-post:" header and offer you a 'reply to list' option means that this is your problem not mine.
---- Can you show me the RFC that specifies the standard that email agents need to recognize a "list post header". RFC2369 describes optional fields for email lists. It says that adherence and use of such fields are *optional* -- meaning they are not required in order to be standards compliant. The fact that this list lists the contact point for this list doesn't mean any email agent is required to use it. Until that time, I suggest you install perl-doc (5.16 or 5.18). That should solve your problem on providing a manpage for pdf2man. That you would preach to me about optional list extensions, and RFC's when you don't install the documentation for the products you "go off on" about not having manpage documentation seems a bit like the pot calling the kettle black. -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
* Linda Walsh <suse@tlinx.org> [12-18-13 20:49]:
Anton Aylward wrote:
Linda, I am not mailing you personally; I am mailing the list. I use 'reply-to-list. I have a modern (intelligent) mail user agent.
recognise the "List-post:" header and offer you a 'reply to list' option means that this is your problem not mine.
---- Can you show me the RFC that specifies the standard that email agents need to recognize a "list post header". RFC2369 describes optional fields for email lists. It says that adherence and use of such fields are *optional* -- meaning they are not required in order to be standards compliant.
AGAIN Linda, it has not to do with *any* rfc, but accepted behavour in *this* forum. You conform to your host's rules/wishes/laws, or not as in your *chosen* case! :0: * ^From:.*suse\@tlinx\.org /dev/null no more problems -- (paka)Patrick Shanahan Plainfield, Indiana, USA @ptilopteri http://en.opensuse.org openSUSE Community Member facebook/ptilopteri http://wahoo.no-ip.org Photo Album: http://wahoo.no-ip.org/gallery2 Registered Linux User #207535 @ http://linuxcounter.net -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
Linda Walsh said the following on 12/18/2013 08:46 PM:
Until that time, I suggest you install perl-doc (5.16 or 5.18).
That should solve your problem on providing a manpage for pdf2man.
That you would preach to me about optional list extensions, and RFC's when you don't install the documentation for the products you "go off on" about not having manpage documentation seems a bit like the pot calling the kettle black.
Its clear that you don't have the slightest clue of the point I was trying to make. Ken is right, and that can be generalized. Thank you, Patrick. *plonk* -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
Ted Byers said the following on 12/17/2013 06:42 PM:
On 13-12-17 06:30 PM, Anton Aylward wrote:
Ted Byers said the following on 12/17/2013 06:02 PM:
[...] Can anyone tell me where it is?
Does this command return anything?
$ apropos perl
Hi Anton,
Thanks for this.
:-)
Yes. I get basically a list of perl modules that have been installed.
What is apropos? I never heard of that before.
Try "man apropos". Hopefully one of the lines thqt 'apropos' retuend was Module::Build (3pm) - Build and install Perl modules Now try $ man 3pm 'Module::Build' The brackets are so that the shell doens't try to interpret the colons. You could alto try $ man perl The "3pm" is the classification. $ man 1 man tell you about the man command and the basics of the classification. It says The table below shows the section numbers of the manual followed by the types of pages they contain. 0 Header files (usually found in /usr/include) 1 Executable programs or shell commands 2 System calls (functions provided by the kernel) 3 Library calls (functions within program libraries) 4 Special files (usually found in /dev) 5 File formats and conventions eg /etc/passwd 6 Games 7 Miscellaneous (including macro packages and conventions), e.g. man(7), groff(7) 8 System administration commands (usually only for root) 9 Kernel routines [Non standard] SO the "3" in the "3pm" means that these are library The "pm" means perl modules. Where they live ... depends. By *convention* most man pages live under /usr/share/man .... somewhere. But there may be other places as well Your environment should have a variable MANPATH that lists the various locations manual pages might live. Try echo $MANPATH That should be set by /etc/profile but could be overridden in a number of places including your own .profile or the bash equivalents. See man pages for that. Oh, and try apropos for various terms to help find man pages. As you can see in /etc/profile, a program names 'manpath' is used to determine the possible paths. This in turn, as "man 1 manpath" will tell you, relies on a config file, /etc/manpath.config, whose format you can read about using "man 5 manpath". This tried to determine what you have installed and where the commonly found man pages might live. It is possible that you might need to update this, but I'd take advice from others before doing so. Please do read all of "man 1 man".
It is great that apropos lists all these perl modules, but what is the next step to actually be able to browse the documentation?
Can you see now why the Whitebeards keep saying to RTFM ? -- Plug into the Formula Maxim: Engineers don't understand security. They tend to work in solution space, not problem space. They rely on conventional designs and focus on a good experience for the user and manufacturer, rather than a bad experience for the bad guy. They view nature as the adversary, not people, and instinctively think about systems failing stochastically, rather than due to deliberate, intelligent, malicious intent. -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
On 13-12-17 08:18 PM, Anton Aylward wrote:
Ted Byers said the following on 12/17/2013 06:42 PM:
On 13-12-17 06:30 PM, Anton Aylward wrote:
Ted Byers said the following on 12/17/2013 06:02 PM:
[...] Can anyone tell me where it is?
Does this command return anything?
$ apropos perl
Hi Anton,
Thanks for this.
:-)
Thanks again.
Yes. I get basically a list of perl modules that have been installed.
What is apropos? I never heard of that before.
Try "man apropos".
Done. OK. I haven't used man in the decades since I finished university. I see the man pages haven't improved much since then. I had assumed that man would have been superceded by something from the twenty first century by now. But maybe my impression of man pages has been a bit jaundiced, as the man pages I endured so long ago, on the departmental machine way back then, were notoriously inaccurate. Our sysadmin used us to find the most egregious errors, which he would then correct on our system once we pointed out that the machine didn't do things the way the documentation said to expect it to do them. But to be fair and honest, he was a master at optimizing the OS (by tweaking the code and rebuilding parts of it), I couldn't tell you whether the problems were original to the the servers or introduced by his optimizations. And to be fair to him, his optimizations were necessary in order to a) prolong the useful life of the machine, as demand grew, and b) make the machines bear a load they would not have otherwise borne. It seemed to me, in some respects, to be penny wise and pound foolish, as the cost of his time optimizing the machines was substantially greater than the difference in cost between what the department bought and what would have actually easily borne the load they put on it OTB. [ big snip]
Your environment should have a variable MANPATH that lists the various locations manual pages might live. Try echo $MANPATH That should be set by /etc/profile but could be overridden in a number of places including your own .profile or the bash equivalents. See man pages for that. MANPATH is empty. But, somehow man is finding what it needs.
Oh, and try apropos for various terms to help find man pages. As you can see in /etc/profile, a program names 'manpath' is used to determine the possible paths. This in turn, as "man 1 manpath" will tell you, relies on a config file, /etc/manpath.config, whose format you can read about using "man 5 manpath". This tried to determine what you have installed and where the commonly found man pages might live. It is possible that you might need to update this, but I'd take advice from others before doing so.
Please do read all of "man 1 man".
Done.
It is great that apropos lists all these perl modules, but what is the next step to actually be able to browse the documentation?
Can you see now why the Whitebeards keep saying to RTFM ?
Oh yes, but the trick, in this case, is to find the manual in order to be able to read it. I guess, the heart of my question was 'where is the manual so I can read it?' Thanks Ted -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
On Tue, Dec 17, 2013 at 08:53:49PM -0500, Ted Byers wrote:
On 13-12-17 08:18 PM, Anton Aylward wrote:
Ted Byers said the following on 12/17/2013 06:42 PM:
On 13-12-17 06:30 PM, Anton Aylward wrote:
Ted Byers said the following on 12/17/2013 06:02 PM: [ bigger snip]
Oh yes, but the trick, in this case, is to find the manual in order to be able to read it. I guess, the heart of my question was 'where is the manual so I can read it?'
my recommendation would be to start with perldoc perlintro -- _|_ _ __|_|_ ._ o| |_(_)(_)|_| ||_)||< | -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
Ted Byers said the following on 12/17/2013 08:53 PM:
What is apropos? I never heard of that before.
Try "man apropos".
Done. OK. I haven't used man in the decades since I finished university. I see the man pages haven't improved much since then. I had assumed that man would have been superceded by something from the twenty first century by now. But maybe my impression of man pages has been a bit jaundiced, as the man pages I endured so long ago, on the departmental machine way back then, were notoriously inaccurate.
I'm sorry you were prejudiced against man pages, but the reality is that this is FOSS. Most programmers consider writing documentation "no fun". That goes for perl as well. Its only firms like IBM. Microsoft and the like where they can charge end users for the produce that they can pay for professional writers to keep bugging the programmers until the writers have enough info to write readable "twenty first century" documentation. You are free to use Windows or some IBM or HP product.
Our sysadmin used us to find the most egregious errors, which he would then correct on our system once we pointed out that the machine didn't do things the way the documentation said to expect it to do them.
ROTHFLMAO! Now I think about it, I've had the same experience with Windows, AIX, some large RAID hardware from a TLA company, HP products all the way down to RS-232 cables, and DG/UX system that claimed it was pure UNIX SVR4.
[ big snip]
Your environment should have a variable MANPATH that lists the various locations manual pages might live. Try echo $MANPATH That should be set by /etc/profile but could be overridden in a number of places including your own .profile or the bash equivalents. See man pages for that.
MANPATH is empty. But, somehow man is finding what it needs.
RTFM
Oh, and try apropos for various terms to help find man pages.
I admit it: I'm very keen on using 'apropos' :-)
Please do read all of "man 1 man".
Done.
Read it again. It answers you other questions elsewhere in this thread.
Oh yes, but the trick, in this case, is to find the manual in order to be able to read it. I guess, the heart of my question was 'where is the manual so I can read it?'
That's what 'apropos' and a proper reading of 'man(1)' is about The latter will tell you how to deal with other formats, how to rebuild the database to include pages and paths (see, for example 'apropos -M') and how to set up /etc/manpath.config and your MANPATH environment variable to make setting permanent. Please do not think everything happens automatically. You do have to set up configuration (and that mean reading the man pages). Simply downloading modules is not enough -- and I would use on of the openSuse repositories before turning to CPAN. -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
Ted Byers wrote:
Done. OK. I haven't used man in the decades since I finished university. I see the man pages haven't improved much since then.
---- The man pages are the main reference for most linux command-line programs. An exception to that is that 'info' pages (best browseable with 'pinfo' which gives you a text-based HTML browser type interface (like lynx), which is needed for some more arcane gnu commands who came up with a "hyperlinked" documentation system that they stuck with in spite of HTML. Also, unlike perl, they provided no translator that automatically translates all of those info pages into HTML (man pages would be 'better', BUT, would lose the hyperlinking)...
I had assumed that man would have been superceded by something from the twenty first century by now.
No more than perl has been replaced with something from the 21st century.
But maybe my impression of man pages has been a bit jaundiced, as the man pages I endured so long ago, on the departmental machine way back then, were notoriously inaccurate.
If they are, it is a bug.
Oh yes, but the trick, in this case, is to find the manual in order to be able to read it. I guess, the heart of my question was 'where is the manual so I can read it?'
There is no central manpage, but a primitive browser might be 'xman', but only works if MANPATH is defined, or if the manpages are located under /usr/man. To use it directly: you might (as root -- or use sudo if you have configured it): sudo ln -s /usr/share/man /usr/man --------------------------------- Note, if you want 'pretty HTML' renderings of your perldoc manpages, install the Mojo & Mojolicious modules (they 'should' come with a bunch of sub-modules)... Looks like "Mojolicious::Plugin::PODRenderer (3pm) - POD renderer plugin" would be key... then you can start a webserver for pod documentation with: ( perl -Mojo -e ' plugin "PODRenderer"; plugin "Pedro"; a()->start' daemon -l http://localhost:3000 & ) Any perlpod pages it can't find on your system, it will try to lookup on the main perl website. Nice looking, but not as convenient as "man <...>" -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
Linda Walsh said the following on 12/18/2013 04:08 PM:
If they are, it is a bug.
And bugs should be reported. Bugs in documentation are 'easy' compared to some others. You can propose a change instead of just complaining. No, make that you SHOULD propose a change instead of just whining. -- How long did the whining go on when KDE2 went on KDE3? The only universal constant is change. If a species can not adapt it goes extinct. That's the law of the universe, adapt or die. -- Billie Walsh, May 18 2013 -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
On 13-12-18 04:37 PM, Anton Aylward wrote:
Linda Walsh said the following on 12/18/2013 04:08 PM:
If they are, it is a bug.
And bugs should be reported.
Bugs in documentation are 'easy' compared to some others. You can propose a change instead of just complaining.
No, make that you SHOULD propose a change instead of just whining.
That's right, subject to the person who encounters the bug knowing how the program in question ought to behave, and that's what we did. But I have seen all too many cases where the person affected by the bug is not in a position to offer such a change. For example, if I am using a C++ compiler, and I find the documentation reflects the latest ANSI standard but the compiler does something different, then it is a bug in the compiler that I could only report (because it is certain I have never been masochistic enough to study all the code in the compiler to see how it supports all the features of the language I am using, and thus could not know how to fix the bug in question). But if the compiler does what is consistent with the ANSI standard but the documentation says something different, then I could suggest the change to the documentation because I understand the ANSI standard and see that reflected in the behaviour of the compiler. On the other hand, it is a safe bet that none of the students in a first course in C++ programming understands the extant standards well enough to know what the compiler ought to be doing: they could only see the discrepancy between what the compiler is doing and what the documentation says it should be doing. The appropriate course of action, then, depends sensitively on who it is that hits the bug. But don't forget, the case I mentioned occurred more than two dozen years ago, and often it was a defect in the original documentation, but even more often it was an error on our sysadmin's part, in not ensuring that the local copy of the docs was consistent with his optimizations. Only he had a hope of determining whether he messed up on his optimization or if he had neglected to update the documentation to reflect the optimizations he'd deployed. But, to add to our "fun" he often told us that the system is fully documented in the code (and he meant the code, not comments embedded in it), and that we ought to just read the code: a rather arrogant response to us as many of his changes were done in assembly (he didn't trust the c compilers of the day to get the optimization right), and he was the only person in the department that knew assembly. There were only about 4, out of a couple hundred, people in our department that knew how to write a program, and all of us, except him, developed our programs in fortran, c, or pascal. He expected us to take the time to learn assembly in order to figure out what he did (and I was never masochistic enough to bother with assembly), and then study the professional literature of the day to find out how operating systems of the day, and the applications he'd installed and optimized, ought to behave, and therefore how the system ought to behave in response to whatever command we were trying to use. How shall I say this: he was brilliant, but his 'people skills' were under developed. I am sure you have seen the type. I respected him, but he was often difficult to deal with. Cheers Ted -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
Ted Byers said the following on 12/18/2013 06:08 PM:
But don't forget, the case I mentioned occurred more than two dozen years ago, and often it was a defect in the original documentation, but even more often it was an error on our sysadmin's part, in not ensuring that the local copy of the docs was consistent with his optimizations. Only he had a hope of determining whether he messed up on his optimization or if he had neglected to update the documentation to reflect the optimizations he'd deployed.
To my mind this raises two questions. The first is 'what was he optimizing?' The kernel algorithms? Well that's a good place to optimise, especially if he an find a way to do so that is of benefit to all users. You say he was inclined to use assembler. Well many people can produce small amounts of code that are better optimized that compilers. That was especially true in the V7 days! It was doubly true as we were porting V7 and BSD2.8 to microprocessors back at the beginning of the 1980s and were using 'template compilers'. But these days compilers are 'expert systems' in code generation and you'd be hard pressed to better them over anything than a very small fragment. That being said, there are a lot of 'internals' whose documentation might get out of phase but really have little to do with what you coding. Could you be more specific please? Then there are things that while they might improve a lot of matters are a bit gratuitous. Perhaps the innards of strcpy could be done with machine specific single opcodes. Perhaps the trig functions could be coded as one assembler routine with different entry points. But that begs the question. How would these improvements get out of phase with the documentation? I can that, for example, the kernel user data structure went though a number of revisions between BSD2.4 and BSD2.8 in the beginning of the 1980s, as it did between V7 and SYSV (think: euid and family). But that only affected a a subset. Were you doing programming of things like 'ps'? The second matter is the sheer arrogance of the guy. Ah, but you go on to mention that!
But, to add to our "fun" he often told us that the system is fully documented in the code (and he meant the code, not comments embedded in it), and that we ought to just read the code: a rather arrogant response to us as many of his changes were done in assembly (he didn't trust the c compilers of the day to get the optimization right), and he was the only person in the department that knew assembly.
"Of the day"? Well 'that was then, this is now' and we're not him, so why the distrust of current MAN pages that have nothing to do with him? There is, I suspect there always has been, a class of programmers who take the attitude that the code is the documentation. These are the same people that never submitted 'design documents' or overviews. There are many apocryphal and true stories about such people. They are almost as bad as the people who write for i = 1 to 10 // i is the loop variable but never tell you why they chose one algorithm over another. Architecture documentation is every bit as important as code documentation. But NEVER confuse them with end-user or operational documentation. -- We all have two choices: We can make a living or we can design a life. -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
On 13-12-18 06:36 PM, Anton Aylward wrote:
Ted Byers said the following on 12/18/2013 06:08 PM:
But don't forget, the case I mentioned occurred more than two dozen years ago, and often it was a defect in the original documentation, but even more often it was an error on our sysadmin's part, in not ensuring that the local copy of the docs was consistent with his optimizations. Only he had a hope of determining whether he messed up on his optimization or if he had neglected to update the documentation to reflect the optimizations he'd deployed.
To my mind this raises two questions.
The first is 'what was he optimizing?' The kernel algorithms? Well that's a good place to optimise, especially if he an find a way to do so that is of benefit to all users. You say he was inclined to use assembler. Well many people can produce small amounts of code that are better optimized that compilers. That was especially true in the V7 days! It was doubly true as we were porting V7 and BSD2.8 to microprocessors back at the beginning of the 1980s and were using 'template compilers'.
I was never masochistic enough to ask what he was doing, after the first time. You see, he'd get excited and start talking tech as if he were talking to himself. Once that happened, what he said was as about intelligible to us as swahili is to most Americans. None of us could make sense of him once he got started. We'd just nod approvingly, especially as he showed us the benchmarks he'd produced showing the benefits (which he needed to get departmental approval for his budget). Back then, I knew number crunching specialists that would resort to assembly, so I knew that if speed were critical, it could be improved by resorting to assembler.
But these days compilers are 'expert systems' in code generation and you'd be hard pressed to better them over anything than a very small fragment.
That being said, there are a lot of 'internals' whose documentation might get out of phase but really have little to do with what you coding. Could you be more specific please?
Then there are things that while they might improve a lot of matters are a bit gratuitous. Perhaps the innards of strcpy could be done with machine specific single opcodes. Perhaps the trig functions could be coded as one assembler routine with different entry points. But that begs the question. How would these improvements get out of phase with the documentation? Like I said, most of us gave up on trying to understand the details of what he was doing. I really didn't care as long as my programs produced
Right, but I was talking about decades ago. provably correct answers (I was, and am, primarily a number cruncher, and spent my time developing either modelling or statistical programs).
I can that, for example, the kernel user data structure went though a number of revisions between BSD2.4 and BSD2.8 in the beginning of the 1980s, as it did between V7 and SYSV (think: euid and family). But that only affected a a subset. Were you doing programming of things like 'ps'?
All the programs I wrote involved some aspect of number crunching. For example, I'd generate test data, for which I knew precisely the distribution moments, and correlations among variables, and write code to do the statistical analyses. The test data was used to verify that the programs were correct, and that they could then be used on data for which we did not know the relationships or correlations. At the time, also, I developed computer based teaching materials, to run on DOS (so I did my share of bit twiddling on video RAM), and I, and the department, bought the first generation PC's. I developed these programs on mine, and delivered them to the department to deploy on their's. Once I had mine, I never had to deal with his optimizations again. ;-) I'd just do my computing on my PC, and deliver the result to my supervisor on a 5 inch floppy.
The second matter is the sheer arrogance of the guy. Ah, but you go on to mention that!
But, to add to our "fun" he often told us that the system is fully documented in the code (and he meant the code, not comments embedded in it), and that we ought to just read the code: a rather arrogant response to us as many of his changes were done in assembly (he didn't trust the c compilers of the day to get the optimization right), and he was the only person in the department that knew assembly.
"Of the day"?
Well 'that was then, this is now' and we're not him, so why the distrust of current MAN pages that have nothing to do with him?
I did say it was decades ago. But, that was also the last time I had to routinely use a unix machine, until I recently started to refamiliarize myself with unix by studying Suse and Ubuntu Linux. I have not yet had sufficient good experiences with man pages to outweigh the unpleasant memories of the bad experiences of decades ago.
There is, I suspect there always has been, a class of programmers who take the attitude that the code is the documentation. These are the same people that never submitted 'design documents' or overviews. There are many apocryphal and true stories about such people. They are almost as bad as the people who write
for i = 1 to 10 // i is the loop variable
but never tell you why they chose one algorithm over another.
agreed. And I have had experience with companies that explicitly forbade us from writing documentation. One president of a consulting company told me it was a waste of time to write documentation. Of course, I wrote documentation anyway, in the form of comments in the code focussed on detailing what the algorithm is and why it was used. Many of the applications I developed are quite complex and it would be a challenge for even a senior engineer to figure out what was done and why (I am sure he'd could do it, but at the cost of spending more time to do so than it would take to redevelop it de novo): part of this is that the mathematics involved is well beyond what an undergraduate student would normally encounter.
Architecture documentation is every bit as important as code documentation. But NEVER confuse them with end-user or operational documentation.
You're absolutely right there. While programmers generally don't like writing documentation, I write it (even though I hate it - it takes longer to get right than it takes to write the code) and I require the programmers I work with to do so too (though I don't let them touch the user documentation as they haven't learned, yet, that users speak a different language than software engineers and programmers). I write my user documentation in cooperation with the support guys (and they're not programmers, but rather guys that spend almost all their time talking with customers and end users; and teaching the latter). Cheers Ted -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
Ted Byers said the following on 12/18/2013 07:14 PM:
But these days compilers are 'expert systems' in code generation and you'd be hard pressed to better them over anything than a very small fragment.
Right, but I was talking about decades ago.
And what system was this? it almost sounds like a few people I knew 20-30 years ago. -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
Ted Byers said the following on 12/18/2013 07:14 PM:
I did say it was decades ago. But, that was also the last time I had to routinely use a unix machine, until I recently started to refamiliarize myself with unix by studying Suse and Ubuntu Linux. I have not yet had sufficient good experiences with man pages to outweigh the unpleasant memories of the bad experiences of decades ago.
MAN pages have a prosaic and fixed format for a number of reasons and are unlikely to change in format. By definition the sections are there for a set purpose. Learning to read them is no different from learning to read music ('tadpoles on telegraph lines') or the entries in the old Texas TTL handbook of my university days. You need to know the command aliases, the command syntax, the meaning of the flags and parameters, the configuration and context and the semantics. Yes you have to learn to read just as I had to learn to read music and learn to read the TTL handbook. You are never going to have 'good experiences' with MAN pages any more than I had 'good experiences' with music notation. It is what it is. There may be a better way of writing music. I know for sure that there are better keyboard layouts that QWERTY and better keyboard mechanisms (such as those used by court recorders http://www.youtube.com/watch?v=qOBs25_g23s). On that theme, see http://plover.stenoknight.com/ Yes, its more logical, its faster, so why don't we all give up QWERTY and go with that? The same reason we don't give up on a lot of things that are well established. You really haven't made it clear what your bad experiences were, what were the man pages that were not kept up to date. There are some 8,000+ man pages on my machine. That just what's under /usr/share/man never mind the .pod files or man pages elsewhere. I don't all are of the same quality, even now. How many of the pages years ago suffer from this sysadmin, what were they, how do they compare with their counterparts here now? If still lacking, how do you think they can be improved? -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
Ted Byers wrote:
The subject says it all. I have searched my suse box top to bottom, as it where, and I can not find the perl documentation. Mind you, that may be a consequence of still trying to master OpenSuse. I am using cpan to get modules, but I regularly consult the documentation for the modules, especially those modules that are large and complex. The was easy on my old Windows machine, as ActiveState's installer put an icon pointing to the index for the HTML version of the documentation. And on my Ubuntu machine, there is an icon attached to the bar on the left pointing to the pod browser (though it seems not all the modules have documentation in pod format - either that or they are not found by the pod browser). But, on my opensuse box (running suse 12.3) I can't find any perl documentation.
Can anyone tell me where it is?
I haven't seen it anywhere else in the thread, but I may have missed it. Apart from perldoc Module::Name, if you are using CPAN to get the modules, then all the documents are available on that site. Or metacpan. -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
participants (9)
-
Anton Aylward -
Dave Howorth -
David Haller -
John Andersen -
Ken Schneider - openSUSE -
Linda Walsh -
Patrick Shanahan -
Ted Byers -
tooth pik