Re: [PLUG] Linux man pages and documentation?

[Paul Heinlein]

On Mon, 25 Mar 2024, MC_Sequoia wrote:

"I will leave aside the fact that no one submits an executable file 
to Linux; each distribution (Red Hat, Debian, etc) picks the 
executable files to include with the Linux kernel."


Ah,so executable files are only developed and maintained by the 
Linux kernel team?


Please re-read the paragraph you quoted. In particular, note the 
subject of the verb "picks."


If I were to write an app, ROFL!, but for the sake of discussion, 
I'd rely on already established executable files that are hopefully 
documented enough for me to hook into?


And not every executable is worthy of its own manual page?

And the Linux kernel team makes the decision on how exes are 
documented or if documented?


--
Paul Heinlein
heinl...@madboa.com
45°22'48" N, 122°35'36" W

Re: [PLUG] Linux man pages and documentation?

[MC_Sequoia]

"I will leave aside the fact that no one submits an executable file to Linux; 
each distribution (Red Hat, Debian, etc) picks the executable files to include 
with the Linux kernel."

Ah,so executable files are only developed and maintained by the Linux kernel 
team?

If I were to write an app, ROFL!, but for the sake of discussion, I'd rely on 
already established executable files that are hopefully documented enough for 
me to hook into?

And not every executable is worthy of its own manual page? 

And the Linux kernel team makes the decision on how exes are documented or if 
documented?

Re: [PLUG] Linux man pages and documentation?

[Paul Heinlein]

On Mon, 25 Mar 2024, MC_Sequoia wrote:

"I was surprised to find < 15% of the command executables were 
documented. Naturally I was hoping for something like 50% to 75%."


I'm starting a new thread from Randall's thread about man pages, 
because I'm getting lost and confused with all the scripting and I'm 
kind of stuck on one very simple common sense idea and that is, how 
can anyone submit an executable file to Linux without documentation?


I will leave aside the fact that no one submits an executable file to 
Linux; each distribution (Red Hat, Debian, etc) picks the executable 
files to include with the Linux kernel.


Here's one scenario where several executable files have no 
documentation. The Texinfo suite, usually accessed via /usr/bin/info, 
includes a program called /usr/sbin/fix-info-dir. It's a shell script 
that replaces missing menu items in info sections. The script has a 
--help option, but no man page. It's there mostly for developers who 
are writing info pages, not for users. Python's pydoc utility sort of 
falls into this category too.


Similarly, the "less" pager distribution often includes a shell script 
called lesspipe.sh. The latter has no man page, though its use is 
documented in the main less man page.


There are other application suites, like git, that come with several 
example or template executables; none has a man page and, honestly, 
who would write a man page for a sample program?


Other program suites like sudo include, e.g., /usr/libexec/sudo/sesh, 
which I can only imagine to be some sort of helper program for the 
main sudo application, but sesh is otherwise undocumented. The same is 
true of the grcat and pwcat utilities distributed with gawk. The 
dovecot imap/pop server goes hog-wild in this manner!


--
Paul Heinlein
heinl...@madboa.com
45°22'48" N, 122°35'36" W