Douglas Stevenson wrote: [snip] > > If there is no such thing... what about adding a section like "3SHELL" > > and "3SHELLMATH" for the two types (or "1SHELLFUNC"... but that would > > not be consistent since shell functions in ksh93/bash/zsh are loadable > > on demand. Using something like "3KSH93SHELL" sounds like an overkill > > and is slightly problematic since normal shell functions can be shared > > between implementations of the POSIX shell if they restrict themselves > > to the POSIX subset of their functionality) ? > > We generally document shell commands on the particular shell man page. For > example, we document the csh built-in commands on csh(1) and the ksh built-in > commands on ksh(1). We also have a shell_builtins(1) man page that lists the > built-in commands for all the shells. If a particular built-in command is > also present as a binary, then we have a separate man page for that command/ > utility in section 1 as well.
Erm, that are builtin commands... but what about shell _functions_ ? AFAIK they are somewhere between builtin commands and normal library functions. Another problem I see is that documenting this in one manual page may bloat the main manual page to a size where IMO a seperate manual page for this topic may be more than justified (remeber that documentation should not be used to torture the users... =:-) ). AFAIK we have to seperate at least between the following categories: 1. builtin commands+shell aliases which are more or less part of the shell's "language", for example "integer"", "float", "nameref" etc. being aliases to the "typeset" builtin which is used to declare variables with special attributes. These builtins+aliases are usually those you either can't disable/remove or it's not recommended to do so... 2. builtin commands which represent normal commands which are builtin for extended functionality or performance (for example ksh93 binds those builtins to a specific path (e.g. /usr/bin/cut for the "cut" builtin etc.) and the implementation keeps them in a seperate library (libcmd)) . 3. builtin shell functions [note: Currently ksh93 has no builtin shell functions, the category is just listed for completeness] 4. shell functions which are loaded on demand 5. builtin shell math functions 6. shell math functions which are loaded on demand In the case of [1], [3] and [5] I would agree that this belongs into the shell's main manual page (except if the topic gets very complex and large (see list of shell math functions in the OS/Net version of ksh93)) but I am not sure how we should handle [2], [4] and [6]. > As for the math functions, they are all documented in section 3m. Uhm... my point was that the shell math functions may reessemble the C99/libm functions but not all their functionality may be available or the behaviour is slightly different from those documented by the 3m manual pages. For example ksh93 in OS/Net currently supports the following shell math functions: -- snip -- acos acosh asin asinh atan atan2 atanh cbrt copysign cos cosh erf erfc exp exp2 expm1 fabs abs fdim finite floor int fma fmax fmin fmod fpclassify hypot ilogb isfinite isgreater isgreaterequal isinf isless islessequal islessgreater isnan isnormal issubnormal isunordered iszero lgamma log log1p log2 logb nearbyint nextafter nexttoward pow remainder rint round scalb scalbn signbit sin sinh sqrt tan tanh tgamma trunc -- snip -- ... my problem is that putting this into the main ksh93(1) manual page with some additional information will likely double or tripple the size of the current manual page. IMO a seperate manual page may be better to cover this topic and some related side-effects, e.g. -- snip -- - ksh93 "printf" builtin supports the "%a" format parameter to print results in base2 instead of base10 which is usefull to prevent inaccuracies caused by conversion between the two bases - Solaris supports things like "negative NaN" - datatype limits (e.g. MIN/MAX for "float", "integer" etc. datatypes can be obtained from "getconf") - portabilty hints (only those platforms which have C99 math support provide the matching C99 math functions in ksh93) etc. -- snip -- My question is now... if we write something like a "shell math functions" manual page... in which section would such a thing belong to ? And which sections could be used if we wanted to document the shell+shell math functions in seperate per-function manual pages ? ---- Bye, Roland -- __ . . __ (o.\ \/ /.o) roland.mainz at nrubsig.org \__\/\/__/ MPEG specialist, C&&JAVA&&Sun&&Unix programmer /O /==\ O\ TEL +49 641 7950090 (;O/ \/ \O;)
