On Sun, Aug 7, 2016, at 02:10 AM, [email protected] wrote:
>
> https://groups.google.com/forum/#!topic/machinekit/8tHlQEbvq2I detailed
> the change to man pages, some while back.
>
> There is also a README in /man in the sources.
I guess we're never going to see eye to eye on this. You guys say
(from the link and README referenced above):
"the overwhelming majority of users are likely to simply
use the web site and never install the local manual pages."
While I strongly agree with this quote from the wikipedia
article on man pages:
"To this day, virtually every Unix command line application
comes with a man page, and many Unix users perceive a
program's lack of man pages as a sign of low quality; "
Further, the second part of your statement "users are likely
to never install the local manual pages" is a self-fulfilling
prophecy. Man pages should be part of the base install.
When "man halcmd" delivers nothing, users are unlikely
to go searching for separate machinekit man-page package.
Instead they will simply think "halcmd is crap - it doesn't
even have a manpage"
> All the static manual pages plus the latest generated ones are on the
> website.
> http://www.machinekit.io/docs/man/man1/
> http://www.machinekit.io/docs/man/man3/
> http://www.machinekit.io/docs/man/man9/
>
> There is a package which can be installed to give all those pages
> locally if required, machinekit-manual-pages
How does the machinekit project match documentation versions
to code versions if you don't have the code and the docs in the
same repository?
With installed man pages, if you are running version 2.6 of a program,
your man pages describe version 2.6. If you are running version
2.8-pre, your man pages describe version 2.8-pre. You don't have
documents describing functions that your code doesn't support,
or code that does things the documentation doesn't describe.
For linuxcnc, all of the docs (man pages, user manuals, html, etc)
are versioned just like the program. At http://linuxcnc.org/docs/
you find links to docs for the current released version, the new
development version, and old versions going back to 2.0. This
is simple to do because code and docs are kept in the same
repository. Having them in the same repository also reinforces
the philosophy that "the code isn't ready to commit until the
documentation is correct", which IMHO is sorely needed here.
It seems like machinekit will always have ONLY whatever docs
are current in the docs repository, and there is nothing to ensure
that the docs match any particular version of the software.
> The static manual pages are part of the ducumentation and can be edited
> and added to there
> https://github.com/machinekit/machinekit-docs/tree/master/docs/man
I will do that.
> I am in the process of properly converting the manual pages, by removing
> troff remnants and formatting for better viewing in .asciidoc / html.
> The process is far from complete, got about as far as /man1/halui so far.
You are taking working TROFF man pages and spending time
and effort to convert them to asciidoc that is only usable from
the website, or if you load a non-standard man-page-package
AND use the non-standard command "mank foo" instead of the
time-honored and user-expected "man foo".
There has got to be a better way. I know little about asciidoc, but
I see multiple sources saying that it can be converted to man page
format. So why not build and install the man pages by default,
in a format that works with "man" instead of "mank"?
> If you have problems contributing a new page, contact me directly, I am
> quite happy to even format plain text to the required asciidoc.
I'm not writing new pages. I'm trying to fix errors and omissions in halcmd
and HAL component man pages. Even in TROFF the formatting is no big
deal - simply copy an adjacent section and change the content while
leaving the formatting alone. Now that I know where you are hiding the
man pages I should have little trouble modifying them.
--
John Kasunich
[email protected]
--
website: http://www.machinekit.io blog: http://blog.machinekit.io github:
https://github.com/machinekit
---
You received this message because you are subscribed to the Google Groups
"Machinekit" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
Visit this group at https://groups.google.com/group/machinekit.
For more options, visit https://groups.google.com/d/optout.
