Re: [Machinekit] [Announcement] Improved documentation and website

[schoone...@btinternet.com]

On 08/08/16 06:01, John Kasunich wrote: On Sun, Aug 7, 2016, at 02:10 AM, schoone...@btinternet.com 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." Qt has not used any ?roff man pages for over 10 years, does not seem to have held them back. 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; " "The six most expensive words in business are, 'We've always done it that way' " Catherine DeVrye 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. You seem to be confusing Machinekit with Linuxcnc, there are no versions, it is a continuous integration process. There are increasingly hooks from the source code to the docs, all protobuf docs are generated directly into the website, as are all the generated component docs built with instcomp or comp. The manual page package is automatically rebuilt if any of its component documents change.   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 are no working troff man pages. What I am doing is cleaning and reformatting existing automatic conversions from troff to asciidoc. This works poorly in either direction and produced asciidoc pages with orphaned troff formatting, which prevents proper clear display. John,  You are uniquely placed to assist us with the content of the documentation, especially HAL related, if you can get past your antipathy for the medium. I hope you will. regards -- 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 machinekit+unsubscr...@googlegroups.com. Visit this group at https://groups.google.com/group/machinekit. For more options, visit https://groups.google.com/d/optout.