embedded man page for ksh function?

embedded man page for ksh function?

Post by Michael Wa » Sat, 14 Apr 2001 22:15:38



I have embedded man page for my_program:

./my_program help=y

will printout the man page.

However I have not figured out how do I do it
for my_function. Requirements:

(1) User does not need to know it is a script or funtion.
The user will use
./my_function help=y. And the man page will tell her it
is a function and how to use it.
(2) The funtion can be used in two ways:
include the funtion in the script, and
FPATH. The embeded man page should not interefere with
either usage.

Thanks.

 
 
 

embedded man page for ksh function?

Post by brian hile » Sun, 15 Apr 2001 03:50:59



> I have embedded man page for my_program:
> ./my_program help=y
> will printout the man page.
> However I have not figured out how do I do it
> for my_function. Requirements:
> (1) User does not need to know it is a script or funtion.
> The user will use
> ./my_function help=y. And the man page will tell her it
> is a function and how to use it.
> (2) The funtion can be used in two ways:
> include the funtion in the script, and
> FPATH. The embeded man page should not interefere with
> either usage.

Hello Michael,

I'm sure your a theoretically aware of the embedded manpages that
I have in the functions and scripts that I periodically publish on
c.u.s. Aren't you duplicated my effort? (although I have never
given the script "src2man" which does the extraction and translation
to a variety of formats.)

Since sourced files (and by this I am of course also talking of
autoloadable functions in files that naturally would be FPATH
accessible) are parsed in their entirely, the trick of embedding
text after an "exit" builtin (which the shell would not scan for
valid tokens afterwards) does not work. Non-functional code should
not be placed into files that may be resolved through FPATH lookup,
says B&K.

Presumably you wish to do some kind of text extraction from the
file based upon some agreed upon format.

Also, if a function relies on being written into a _unique file_,
this could be problematic as robust design should dictate that this
assumption would produce erratic results at worst and ambiguous or
wrong results at best. Recall that the scripting idiom of autoloadable
function _suites_ is to necessarily define many functions in _one_
file. What to do then?

To use a command-line option is a good idea to produce this man-page
instead of merely outputting a usage synopsis, BUT...

(1) The format you use is against POSIX.2/XPG4 conventions. In any
regard, the _correct_ way to pass local variable values into
functions is to do so just as subshell executables: "var1=value1
var2=value2 my_function".

(2) My src2man script does man-page translation to a variety of
text formats, including nroff, HTML, and (eventually) SGML. My
intuition is that format gains is more important than accessibility
gains.

=Brian

 
 
 

embedded man page for ksh function?

Post by Michael Wa » Sun, 15 Apr 2001 15:49:25


Quote:>I'm sure your a theoretically aware of the embedded manpages that
>I have in the functions and scripts that I periodically publish on
>c.u.s. Aren't you duplicated my effort? (although I have never
>given the script "src2man" which does the extraction and translation
>to a variety of formats.)

I definitely will not duplicate your effort. My needs is simpler,
I just need to have "my_script help=y" and "my_function help=y"
to produce man pages. And instead of writing my own code, I rely
on "perldoc" and related utilities.

I definitely notice your "src2man", but as I commented before,
your posting isn't complete and I can not at this point directly
benefit from your effort.

Quote:>Since sourced files (and by this I am of course also talking of
>autoloadable functions in files that naturally would be FPATH
>accessible) are parsed in their entirely, the trick of embedding
>text after an "exit" builtin (which the shell would not scan for
>valid tokens afterwards) does not work. Non-functional code should
>not be placed into files that may be resolved through FPATH lookup,
>says B&K.

I did some experiment after reading your post. I found that "return"
can be used in place of "exit" for functions.

Quote:>Presumably you wish to do some kind of text extraction from the
>file based upon some agreed upon format.

Yes, POD.

Quote:>Also, if a function relies on being written into a _unique file_,
>this could be problematic as robust design should dictate that this
>assumption would produce erratic results at worst and ambiguous or
>wrong results at best. Recall that the scripting idiom of autoloadable
>function _suites_ is to necessarily define many functions in _one_
>file. What to do then?

If the man page is imbedded to each of the functions, I do not think
one file multiple functions would be an issue.

Quote:>To use a command-line option is a good idea to produce this man-page
>instead of merely outputting a usage synopsis, BUT...
>(1) The format you use is against POSIX.2/XPG4 conventions. In any
>regard, the _correct_ way to pass local variable values into
>functions is to do so just as subshell executables: "var1=value1
>var2=value2 my_function".

(a) "my_function help=y" or "my_script help=y"
is different than
(b) "help=y my_function" or "help=y my_script"

In (a) "help=y" the argument for "my_function" or "my_script",
and I do not think it is against POSIX.2/XPG4 conventions. Does
POSIX.2/XPG4 specify what argument has be like?

I prefer to use (a) because:
(1) It avoids site effects. You can not prevent a user
defining "help=y" and her .profile for some other purposes.
So in your program, you do not know if the user set
help=y just for this program if you use (b) form.
(2) Because both the key and value are in the argument,
I can parse the argument and make "help=y" and "Help=Y"
equivalent.

For "my_script" we can use the "exit" technique, and
"my_function" we can use the "return" technique. Then
And the syntax is the same
"my_function help=y"
"my_script help=y"

But for functions, FPATH needs to be set and
for scripts PATH needs to be set. And this requires
the users to know which is script and which is function.
Ask the users to set both PATHs before hand probablly the
best choice.

Quote:>(2) My src2man script does man-page translation to a variety of
>text formats, including nroff, HTML, and (eventually) SGML. My
>intuition is that format gains is more important than accessibility
>gains.

POD parsers will convert POD to all sorts of formats.
 
 
 

1. Standard man pages to "Catted" man pages!

To Anyone Interested:

        How does one take a standard "troff"ed (?) man page that comes
with a package off the net (ending in .1, .2, etc) and turn in into a
compressed, "cat"ted man page (ending in .1.Z, .2.Z, etc) that are
stored in the directory /usr/man/catN (N = 1,2,3,...) that can be read
by the standard man utility that comes with the SLS distribution?  I'm
sure that this is trivial to do, and is probably written down
SOMEWHERE, but I've got only so many hours a day I can spend reading
FAQs and HOWTOs.  Thanx in advance...
--

                                Dr. Richard Procassini
                                Methods Development Group
                                Mechanical Engineering Department
                                Lawrence Livermore National Laboratory
                                Mail Stop L-122
                                P.O. Box 808
                                Livermore, CA  94551

                                (510)424-4095


2. The Webalizer 0.98

3. How to format BSD man pages (groff man) using "classical" troff man?

4. Installation problem: it won't start to install at all.

5. Wanted: man page for ksh

6. Netatalk Source BAD

7. Man pages for libproc.so.1.00 functions?

8. How to find out versions of lib?

9. Man Pages for c/c++ functions/libs?

10. Include just one or all headers listed in man page for function

11. Which package are man pages for C functions like (strtok and strcat etc) stored in

12. Man pages for C/C++ functions ...?

13. Man pages for system functions