[Announcement] Improved documentation and website

[Bas de Bruijn]

Dear list,

Last few weeks, Michael, Mick and me have been working on getting the website and documentation tools and flows into better shape. We have tried to make reading, searching, and contributing to the documentation as easy as possible.

The highlights:

- There’s 1 place to read: machinekit.io/docs This holds all the documentation we have
- 2 click editing of content. A wiki like experience, without the downside of a wiki. http://www.machinekit.io/docs/documenting/contributing-documentation/#2-click-editing-with-edit-me-button
- The power of diagrams has been unlocked. Which should make documentation a LOT more readable. http://www.machinekit.io/docs/documenting/diagram-examples/ 
- Component manpages are automatically integrated in the site, see for example offsetn http://preview.machinekit.io/docs/man/man9/offsetn/ 

We have tried to lower the barrier as much as we could.

We specifically did not focus on content and structure yet, just getting eveything together into a single format, git backed, automatically served, and easy to edit.

There’s still tons of work to do on the documentation, and we can’t do it all on our own.

Therefor we would like to ask _you_ to:

- Read through this short overview first: http://www.machinekit.io/docs/site/about-this-site/index.html
- Read through the docs and submit edits where you think the docs are wrong or incomplete
- Submit any new material you feel is currently missing through the SandBox section http://www.machinekit.io/docs/sandbox/index.html
- Raise any issues through the specific tracker issues listed in http://www.machinekit.io/docs/site/about-this-site/#discussing-improvements-use-the-a-href-https-github-com-machinekit-machinekit-docs-issues-docs-tracker-a
- Help improve documentation!

Feel free to comment generally via this thread.

Cheers,

Mick, Michael and Bas

[sliptonic]

Congratulations!  Excellent work!  This is already a huge improvement.

[Håkan Båstedt]

Thanks for all the work on the documentation.
I am trying to follow that to set up Machinekit on a Beaglebone with CRAMPS.
First time ever, never used Machinekit or Beaglebone although I am pretty fluent in Linux
and know some related things from working with 3d printers, but anyway.

I will give some feedback here.
1. Which image to use? There are several options, but really I would like to have a recommendation. I chose jessie.
2. I think the point with configuring apt is not 100% correct when it comes to libczmq-dev. I failed to follow the instructions
to use "sid". Instead it now seems that libczmq-dev is available in jessie so that part is not needed. I messed around
quite a bit trying to follow the instructions, so can't be 100% though.
3. Flashing the image to eMMC - I don't know if it has been done. Should I do it? Seems info in uEnv.txt doesn't match.
4. First at this point it was clear to me that I was using xenomai and that was the version to install.
5. I was running this without a screen, so tightvncserver was installed. That wasn't good enough due to lacking OpenGL.
x11vnc worked fine though.
6. Had not attached the CRAMPS board, so when I chose the CRAMPS sample configuration I got some weird errors.
First after quite a bot of googling I found out that the board has to be connected.
7. I felt I should try to update the documentation on the libczmq-dev topic. But it is quite a big step to take, being
a real beginner and not sure if I am stupid or the documentation is wrong. Also using git to clone and submit
changes - it is also a large threshold. Nothing a beginner will do for sure. At least not me.

Anyway these are my comments and feedback. When being a beginner, nothing is obvious and
things can't be spelled out clear enough sometimes.

/H

[Bas de Bruijn]

Hi Hakan,

Thanks for the feedback, I’ve commented on the parts I have some knowledge of.

On 16 Jun 2016, at 11:41, Håkan Båstedt <hakan....@gmail.com> wrote:

Thanks for all the work on the documentation.
I am trying to follow that to set up Machinekit on a Beaglebone with CRAMPS.
First time ever, never used Machinekit or Beaglebone although I am pretty fluent in Linux
and know some related things from working with 3d printers, but anyway.

I will give some feedback here.
1. Which image to use? There are several options, but really I would like to have a recommendation. I chose jessie.

IMO you chose the right one.

2. I think the point with configuring apt is not 100% correct when it comes to libczmq-dev. I failed to follow the instructions
to use "sid". Instead it now seems that libczmq-dev is available in jessie so that part is not needed. I messed around
quite a bit trying to follow the instructions, so can't be 100% though.
3. Flashing the image to eMMC - I don't know if it has been done. Should I do it? Seems info in uEnv.txt doesn't match.

I prefer to keep my image on the SD where I can make backups of the SD, or try another image. But that’s personal.

4. First at this point it was clear to me that I was using xenomai and that was the version to install.

Are you going to do development on the BBB? if not, you shouldn’t have to install anything.

5. I was running this without a screen, so tightvncserver was installed. That wasn't good enough due to lacking OpenGL.
x11vnc worked fine though.
6. Had not attached the CRAMPS board, so when I chose the CRAMPS sample configuration I got some weird errors.
First after quite a bot of googling I found out that the board has to be connected.
7. I felt I should try to update the documentation on the libczmq-dev topic. But it is quite a big step to take, being
a real beginner and not sure if I am stupid or the documentation is wrong. Also using git to clone and submit
changes - it is also a large threshold. Nothing a beginner will do for sure. At least not me.

We have an “edit this page” button, which will take you to the source, and following these instructions http://www.machinekit.io/docs/documenting/contributing-documentation/#2-click-editing-with-edit-this-page-link will enable you to have GitHub make a new branch on your own account, where you can make a PR.

Anyway these are my comments and feedback. When being a beginner, nothing is obvious and
things can't be spelled out clear enough sometimes.

yeah I know the feeling, but keep up the comments, cause that’s th only way to understand where the documentation needs to be improved.

Cheers,

Bas

/H

[Boris Skegin]

2. I think the point with configuring apt is not 100% correct when it comes to libczmq-dev. I failed to follow the instructions
to use "sid". Instead it now seems that libczmq-dev is available in jessie so that part is not needed. I messed around
quite a bit trying to follow the instructions, so can't be 100% though.

I do not see    libczmq-dev available in jessie https://packages.debian.org/search?keywords=libczmq-dev,

I do not see libczmq-dev in backpoers https://backports.debian.org/changes/jessie-backports.html either - yet.

If  libczmq-dev appears in jessie, then it will appear only in jessie-backports because of Debian policy.

It is almost there https://anonscm.debian.org/cgit/collab-maint/czmq.git?h=jessie-backports ...

Meanwhile try to build  libczmq-dev:

https://github.com/machinekit/machinekit-docs/issues/71#issuecomment-220230936

[Bas de Bruijn]

> On 16 Jun 2016, at 21:03, 'Boris Skegin' via Machinekit <machi...@googlegroups.com> wrote:
>
> Meanwhile try to build libczmq-dev:
> https://github.com/machinekit/machinekit-docs/issues/71#issuecomment-220230936

I'm not aware that one should have to manually build this. Maybe someone more knowledgeable could chime in.

But please discuss this in another thread or issue. We don't want to dilute this thread (At least I don't :) )

Cheers,
Bas

[Håkan Båstedt]

If we only look at the documentation, then I think it could be clearer around the libczmq library.
I spent quite some time to get it installed. From the documentation it seems to be needed,
and also libczmq-dev. I can not judge if that is correct, perhaps in a month's time it will be clear.

It sounds like I am complaining, but I am grateful for the work you guys have put in to the documentation.

[Joseph]

The update looks great.  Good work.

Not certain where to post this - I started with new uSD cards.  Burned current Raspbian distro (27 May 2016) onto the cards.  Plugged into RPi3 (first) then updated and upgraded to start current. 

Then I ran through the "Getting Started" section to "Setting up Machinekit on a Platform" to "5. Debian Jessie on ARM7(RPi2)".  The section "Apt Packages for Jessie" worked as expected.  Then on to "Install the Kernel."  Updating the raspberrypi-bootloader returns "already the latest."  Next is "install kernel."  "apt-get install linux-image-rpi2-rt" fails as the package is no longer available.  Is there another repository which must be specified?  Or perhaps the image name has changed? 

Thank you,   Joe

[schoo...@btinternet.com]

http://deb.machinekit.io/debian/pool/main/l/linux-rt/linux-image-rpi2-rt_4.4.4-rt9-v7+-7_armhf.deb

Seems to be where it should be.

Try running 'apt-get update' and run 'apt-get install linux-image-rpi2-rt' again.

regards

Thank you,   Joe

--
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+...@googlegroups.com.
Visit this group at https://groups.google.com/group/machinekit.
For more options, visit https://groups.google.com/d/optout.

[schoo...@btinternet.com]

The Packages file at
http://deb.machinekit.io/debian/dists/raspbian/main/binary-armhf/Packages

contains

Package: linux-image-rpi2-rt
Source: linux-rt
Version: 4.4.4-rt9-v7+-7
Architecture: armhf
Maintainer: GP Orcullo <kinsa...@gmail.com>
Installed-Size: 54632
Suggests: linux-firmware-image-rpi2-rt
Provides: linux-image-rt, linux-image-rt-4.4, linux-modules-rt-4.4.4-rt9-v7+
Homepage: http://www.kernel.org/
Priority: optional
Section: kernel
Filename: pool/main/l/linux-rt/linux-image-rpi2-rt_4.4.4-rt9-v7+-7_armhf.deb
Size: 15451920
SHA256: 1050aab116f1eef1c240583cf7b03f5f546e494382084bffb901e7276fc95382
SHA1: 2eec295443d3b4dd7e0ef4cbf3003575a8b5ac93
MD5sum: c4eb9daae673c98a17a43a445b151785
Description: Linux kernel, version 4.4.4-rt9-v7+
 This package contains the Linux kernel, modules and corresponding other
 files, version: 4.4.4-rt9-v7+.

so as far as I can tell it is correct.

Anyway you have sorted it, if all else fails 'dpkg -i' locally on a downloaded package works too :)

On 30/07/16 15:09, Joseph Heath wrote:

Hello,

I am confident I did run "apt-get update" after adding machinekit to the repository list, several times, using both  RPi2 and RPi3 just in case there was some hidden hardware check, but ran through it again anyway.  The response I get to 'apt-get install linux-image-rpi2-rt' is "E: Unable to locate package linux-image-rpi2-rt".  Perhaps the "Packages" file for jessie changed?

In any case, thank you for the direct link to the image.  I was able to install using that.

All the best,   Joe

You received this message because you are subscribed to a topic in the Google Groups "Machinekit" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/machinekit/Wk2fL2rKijM/unsubscribe.
To unsubscribe from this group and all its topics, send an email to machinekit+...@googlegroups.com.

[John Kasunich]

On Mon, May 30, 2016, at 07:49 AM, Bas de Bruijn wrote:
> Dear list,
>
> Last few weeks, Michael, Mick and me have been working on getting the website and documentation tools and flows into better shape. We have tried to make reading, searching, and contributing to the documentation as easy as possible.
>
> The highlights:
>

> - There’s 1 place to read: machinekit.io/docs <http://machinekit.io/docs> This holds all the documentation we have
> - 2 click editing of content. A wiki like experience, without the downside of a wiki. http://www.machinekit.io/docs/documenting/contributing-documentation/#2-click-editing-with-edit-me-button <http://www.machinekit.io/docs/documenting/contributing-documentation/#2-click-editing-with-edit-me-button>

Exactly what is the downside of a wiki?

Clicking the "edit me" button does not let me edit the page.
It expects me to log into (and thus to have) a github account.
Github might not be an obstacle to developers, but it is to users.
You say you want users to contribute to the documentation, so
please make it easy to do so.

> We have tried to lower the barrier as much as we could.
> We specifically did not focus on content and structure yet, just
> getting eveything together into a single format, git backed,
> automatically served, and easy to edit.

I understand. You have nice shiny new infrastructure.

Unfortunately, you have the same content. Still missing lots
of stuff. Still out of date.

> There’s still tons of work to do on the documentation, and
> we can’t do it all on our own.
> Therefor we would like to ask _you_ to:

Who is "you" in the above sentence?

Users of Machinekit?
Or the other developers who have contributed to Machinekit?

There are time when users can make valuable contributions
to documentation. But most of the time, when someone writes
new code, the ONLY person who can document it is the one who
wrote it, because he is the only one who knows what problem
it is trying to solve, how it solves the problem, and what its
requirements and limitation are.

> - Read through this short overview first: http://www.machinekit.io/docs/site/about-this-site/index.html <http://www.machinekit.io/docs/site/about-this-site/index.html>

> - Read through the docs and submit edits where you think the docs are wrong or incomplete

> - Submit any new material you feel is currently missing through the SandBox section http://www.machinekit.io/docs/sandbox/index.html <http://www.machinekit.io/docs/sandbox/index.html>
> - Raise any issues through the specific tracker issues listed in http://www.machinekit.io/docs/site/about-this-site/#discussing-improvements-use-the-a-href-https-github-com-machinekit-machinekit-docs-issues-docs-tracker-a <http://www.machinekit.io/docs/site/about-this-site/#discussing-improvements-use-the-a-href-https-github-com-machinekit-machinekit-docs-issues-docs-tracker-a>
> - Help improve documentation!

I would like to contribute. So I'm going to walk you
through the process as I am experiencing it right now.

The last time I tried using Machinekit was in February.
I had much the same frustrations with documentation
back then, and I did create a github account at that
time. One obstacle overcome - normal users won't be
so lucky.

So this time (after trying to remember the password)
I was able to log in.

Now I'm on this page:
https://github.com/machinekit/machinekit-docs//edit/master/docs/documenting/contributing-documentation.asciidoc
In big letters it says:
You need to fork this repository to propose changes.
Sorry, you’re not able to edit this repository directly—
you need to fork it and propose your changes from there instead.

As a user, I have no idea what a "repository" is and a fork
is for eating. So I click on "learn more".
It explains that forking makes a copy of a repository so I
don't screw up the original. OK, makes sense. I still don't
know what a repository is. Specifically, the question in my
mind is - am I about to make a copy of the page I wanted
to edit? or of the entire documentation tree? or of the
entire project, source and all?

Ignoring that question, I go back and click on Fork and
propose changes.

I edited the page (added a line pointing out that you need
a github account, and the link to sign up). Then instead of
the "save" that a user expects, I have to click on "propose
changes".

Am I done? Nope. I'm taken to yet another page, where I
am shown a diff of my change and have to click yet another
button to "create pull request". So I do.

Am I done? Nope. Yet another page, more crap that I don't
care about, and yet another "create pull request" button.
So I click it.

I get a page that shows some checks need to happen, and
if I sit there for a while the yellow eventually turns green.
There is a button at the bottom to close the pull request,
but I don't know if that means "close" as in "finish", or as
in "cancel".

I have no idea how to get back to the page I was originally
on when I clicked the "edit this page" button. (Other than
by hitting "back" a bunch of times, or going back to the
original link. I suppose I should have clicked "open in new
tab" when I wanted to edit the page.

Having made it back to the original page, I find that my
edit isn't there...

Git and github might be good for programmers who need to
carefully control access to source code or master documents.
Git and github are NOT friendly to a random user who wants
to make a minor (or even not-so-minor) improvement to the
documents.



--
John Kasunich
jmkas...@fastmail.fm

[Charles Steinkuehler]

Great points John!

It sounds like we should at least have a "walk-through" page with how
a new user can submit a PR for the docs. Ideally, this could be
linked from the various intermediate pages you hit when trying to
"Edit this page", but I'm not sure if that's possible.

Charles Steinkuehler
cha...@steinkuehler.net

[John Kasunich]

On Sun, Jul 31, 2016, at 10:50 PM, Charles Steinkuehler wrote:
> Great points John!
>
> It sounds like we should at least have a "walk-through" page with how
> a new user can submit a PR for the docs. Ideally, this could be
> linked from the various intermediate pages you hit when trying to
> "Edit this page", but I'm not sure if that's possible.
>

Well, my point is only half-made.

What I'm really trying to say is not "github is hard to use and needs
more process details or a better walk-thru".

I'm trying to day "github is hard to use and not the appropriate tool
for user-submitted documentation revisions".


--
John Kasunich
jmkas...@fastmail.fm

[schoo...@btinternet.com]

Hi Joe,

Now corrected
https://github.com/machinekit/machinekit-docs/pull/209

Thanks for your patience pinpointing what was wrong.

It looks as though all the packages required should be in the raspbian repo,
if you come across any other related issues please highlight them,
don't know how many people actually use rpi, I certainly don't.

regards

On 30/07/16 18:00, Joseph Heath wrote:

Yes, in the Raspbian directory structure.

The instructions for setting up Machinekit on the ARM7 (RPi2) use Jessie, not Raspbian.

http://www.machinekit.io/docs/getting-started/installing-packages/

scroll down to "5. Debian Jessie on ARM7 (RPI2)" and click the first link,
http://www.machinekit.io/docs/getting-started/APT-packages-jessie/

and you are presented this set of instructions

sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 43DDF224
sudo sh -c \
  "echo 'deb http://deb.machinekit.io/debian jessie main' > \
  /etc/apt/sources.list.d/machinekit.list"
sudo apt-get update

Change that "jessie" above to "raspbian" and things work as expected. 

I'd suggest changing the instructions to use the Raspbian reference (splitting the RPI from generic jessie) or copy the raspbian linux-image-rpi2-rt info into the jessie armhf distribution structure.

All the best,   Joe

[Bas de Bruijn]

Hi John,

Thanks for the feedback, especially the part where you run thru the edit-me process.

On 01 Aug 2016, at 00:59, John Kasunich <jmkas...@fastmail.fm> wrote:

On Mon, May 30, 2016, at 07:49 AM, Bas de Bruijn wrote:

Dear list,

Last few weeks, Michael, Mick and me have been working on getting the website and documentation tools and flows into better shape. We have tried to make reading, searching, and contributing to the documentation as easy as possible.

The highlights:

- There’s 1 place to read: machinekit.io/docs <http://machinekit.io/docs> This holds all the documentation we have
- 2 click editing of content. A wiki like experience, without the downside of a wiki. http://www.machinekit.io/docs/documenting/contributing-documentation/#2-click-editing-with-edit-me-button <http://www.machinekit.io/docs/documenting/contributing-documentation/#2-click-editing-with-edit-me-button>

Exactly what is the downside of a wiki?

The most important reasons why we didn’t use a wiki were:

• A wiki has little implicit structure. Personally I think structure is the most important thing that readers need (especially if you’re new).
• Wiki’s very fast become a mess and are hard to maintain (that has nothing to do with the current state of the docs btw :) )

And the most important reasons to use the repository and the jekyll build were:

• we can use C4 on the docs repository (which is social contract)
• diagrams and text are rendered and readable. Which was a huge complaint... readability.

Clicking the "edit me" button does not let me edit the page.
It expects me to log into (and thus to have) a github account.
Github might not be an obstacle to developers, but it is to users.
You say you want users to contribute to the documentation, so
please make it easy to do so.

We have tried to lower the barrier as much as we could.
We specifically did not focus on content and structure yet, just
getting eveything together into a single format, git backed,
automatically served, and easy to edit.

I understand.  You have nice shiny new infrastructure.

Unfortunately, you have the same content.  Still missing lots
of stuff.  Still out of date.

yes that’s true.

There’s still tons of work to do on the documentation, and
we can’t do it all on our own.
Therefor we would like to ask _you_ to:

Who is "you" in the above sentence?

Users of Machinekit?
Or the other developers who have contributed to Machinekit?

There are time when users can make valuable contributions
to documentation.  But most of the time, when someone writes
new code, the ONLY person who can document it is the one who
wrote it, because he is the only one who knows what problem
it is trying to solve, how it solves the problem, and what its
requirements and limitation are.

all who feel that they can and want to help out by fixing a typo, a link, an error or maybe write down how to set up something that they have done.

I agree with your statement that the person writing code is also the one who should document. But we have what we have, and like you said. A lot of stuff is really out of date.

This should be better explained in the instructions. Your PR has been built in preview.machinekit.io and you can view your change there. You can add more commits if you’re not satisfied. And a maintainer will merge the PR in the end.

I have no idea how to get back to the page I was originally
on when I clicked the "edit this page" button.  (Other than
by hitting "back" a bunch of times, or going back to the
original link.  I suppose I should have clicked "open in new
tab" when I wanted to edit the page.

good point. We should look if we can do this automatically from the button link

Having made it back to the original page, I find that my
edit isn't there...

Git and github might be good for programmers who need to
carefully control access to source code or master documents.
Git and github are NOT friendly to a random user who wants
to make a minor (or even not-so-minor) improvement to the
documents.

I understand your concern, and we need to look if we can improve the “2 click edit” explanation page, where there can be some more background about what to expect.

Can you tell me what exactly is missing in the instructions? http://www.machinekit.io/docs/documenting/contributing-documentation/#2-click-editing-with-edit-this-page-link

does it need more pictures? does it need more detailed explanation what’s happening like your example above? Something else?

Bas

--
 John Kasunich
 jmkas...@fastmail.fm

[John Kasunich]

Documentation frustrations continue...

I really don't want to be "that guy" who complains all the time
and doesn't actually fix anything. Today's complaints are the
results of an attempt to fix documentation.

I figured I would start with something simple. The HAL
"newthread" command is undocumented, I figured I would
contribute documentation.

I found this page:
http://www.machinekit.io/docs/developing/machinekit-developing/
And I followed those instructions to the letter to install machinekit
on my beaglebone green.
I was able to compile from source (it took an hour, the bone is SLOW).

I edited the source of halcmd to fix the built-in help. Built it and tested
it. Works great.

Then I wanted to update the halcmd man-page. "man halcmd" gave
me nothing. On this page:
http://www.machinekit.io/docs/hal/tools/
I discovered that RIP builds don't install man pages. Seems odd, the
script at scripts/rip-environment does attempt to set a man path, but
I don't know the finer points of that stuff.
Anyway, I try the "man -M docs/man halcmd" approach as shown on
that page. Nothing. Then I look at my checkout, and the man directory
tree contains only an empty man9 directory... Where are the damn
man pages?

I followed the checkout, configure, and build instructions to the letter.
Why no man pages? If your default is to not build them (Why?) then
the configure switch to turn them on should be documented on
http://www.machinekit.io/docs/developing/machinekit-developing/
Even if you're not building them, where is the troff source? (or asciidoc
source, or whatever you are using to make man pages)

I also found an unrelated bug (addf will allow you to add a function
that uses floating point to a thread that doesn't support floating
point). While trying to investigate that it seems like the halcmd -v
option doesn't work like it used to (but I haven't had a chance to
really investigate that, might be my fault).

Anyway, I only had a couple hours. I thought I could accomplish
something in that time but all I did is drive my frustration level
higher. Leaving for a while, hopefully by tomorrow someone can
explain how I can contribute an improvement to a man page when
the checkout doesn't include the man page!


--
John Kasunich
jmkas...@fastmail.fm

[schoo...@btinternet.com]

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.

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

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 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.

If you have problems contributing a new page, contact me directly, I am
quite happy to even format plain text to the required asciidoc.

regards

>

[John Kasunich]

On Sun, Aug 7, 2016, at 02:10 AM, schoo...@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."

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
jmkas...@fastmail.fm

[schoo...@btinternet.com]

On 08/08/16 06:01, John Kasunich wrote:

On Sun, Aug 7, 2016, at 02:10 AM, schoo...@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

[John Kasunich]

On Mon, Aug 8, 2016, at 04:01 AM, schoo...@btinternet.com wrote:
>
> On 08/08/16 06:01, John Kasunich wrote:
> > On Sun, Aug 7, 2016, at 02:10 AM, schoo...@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

As I said, we're never going to agree on this. I don't see the relevance
of QT. It is an application platform, not something that "users" have
to deal with.

I see halcmd as something like grep. It runs from the command line,
and its documentation should be available from the command line.

> > 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.

I'm not confusing them, I'm comparing them.

LinuxCNC understands that users install a version, make a machine
work, and stay there. Most users don't want to be on a treadmill of
constant updates. They want a stable version that works, while
the developers continue to progress on the next version. Maybe
1% to 5% of users are interested in the bleeding edge and are
willing to run the development version. The rest just want stable.

To be blunt - machinekit seems to be oriented toward developers
who want to code cool programs, rather than machine builders and
users who want to make cool machines. This is ironic given that
machinekit was started by Michael H, who wanted to extend the
capabilities of HAL to applications other than G-code driven machine
tools.

Maybe the problem is my perspective. I'm frustrated because it
seems like machinekit isn't mature/stable enough to simply USE.
Perhaps that is a good thing - progress often requires instability.
But I'm not interested in progress, I'm interested in building a
HAL based machine controller on beaglebone.

> 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.

Users don't read source code.
Users don't have any reason to know or care what a protobuf is.

Autogenerated comp docs are a good thing. Sadly, all too many
of them are nothing more than a pin list, because the developers
write little or no prose description, relying entirely on the
autogenerated stuff to tell the user what the component does.

This problem is not unique to machinekit. LinuxCNC has the
same problem, especially with some newer components. It is
very much driven by the personality of the person who wrote
the component. Some folks want their components to be usable
by anyone and write docs accordingly, others are happy as soon
as it works well enough to meet their personal needs.

> 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.

They worked when machinekit was forked from LinuxCNC.

> 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.

Understood, that is thankless work and I'm glad you are doing it.

But "man halcmd" doesn't work, and that seems to be a policy
decision by machinekit leadership. I simply cannot agree with
that decision. Such is life.

> 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 would like to, and I will where I can.

However - I am here primarily as a user. I have three projects
that are ideally suited to a beaglebone+LCD touchscreen as
a controller. LinuxCNC does not support that platform.
Machinekit does. So here I am.

As a user, I'm accustomed to typing "man foo" when I want
information about foo. Every time "man foo" fails, it is just
another little jab from the machinekit developers saying
"you are not the kind of user we care about, go away".

So yes, it gets irritating after a while, and sadly I let that
irritation out on this mailing list. If I didn't want to make
the beaglebone work so much, I would indeed have gone
away a while ago.

As a user, I need docs that accurately describe the HAL language
as it exists in the machinekit world. The docs that existed when
machinekit was forked were pretty good at describing the HAL
language as it existed at that time. Since then, the machinekit
devs have kept many things the same, and the documentation
for those things is still accurate. The machinekit devs have also
changed many other things. Sadly, they have not documented
some (many) of their changes.

Micheal wrote the "newthread" command over a year ago.
It is much better then the old "threads component" method
of creating a thread. But he didn't document it at all. Nothing
in the man page. Nothing in the halcmd built-in help. Nothing
in any other document on the website. He finally (yesterday,
after my griping) deprecated the old approach and updated
the sample configs to use the new approach.

--
John Kasunich
jmkas...@fastmail.fm

[John Kasunich]

Oops, I hit send before adding one important point:

>
> > 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.

Unfortunately the content that I know about is what existed at
the time of the LinuxCNC/machinekit fork. And the vast majority
of that was already well documented.

The holes in the machinekit documentation are mostly things
that the machinekit devs have added or changed, and I have no
specific knowledge of their changes. (for example newthread)

If anything, my knowledge of how LinuxCNC did things might
make it harder for me to wrap my brain around how machinekit
does them.

For example, I still think of RT components as kernel modules.
I know that is no longer the case with machinekit. However,
as a USER, it shouldn't make a bit of difference. As long as
"loadrt", "newthread" and "addf" work *as documented*,
the implementation is irrelevant.

Since I want to write documentation for users and from a
user's viewpoint, such implementation details shouldn't
matter. What matters is that the code does what the docs
say it does, and vice versa.

--
John Kasunich
jmkas...@fastmail.fm

[schoo...@btinternet.com]

I don't think it will be fruitful to enter into any further debates.

However:

>>  I see halcmd as something like grep. It runs from the command line, and its documentation should be available from the command line.

>> But "man halcmd" doesn't work, and that seems to be a policy decision by machinekit leadership. I simply cannot agree with that decision. Such is life.

"mank halcmd" DOES work on the command line.

'Anything related to machineKit, add a K'

I did consider the feasibility of having an 'interception script'  via /etc/alternatives for man, to fork machinekit display requests one way and normal man pages another.
However since there is no Machinekit distro and machinekit could be installed on any kind of linux distro, that was not going to be achievable without a lot of bother
and undoubted breakages.

I don't think typing one extra letter is too bad a compromise.  Try it.

regards

PS.

I have now removed all dependencies from the package `machinekit-manual-pages`.  This will kick in after the next website production build, or by 0934 CET tomorrow
at the latest.
Then one will be able to install the manual pages even if you don't have machinekit installed, for study or whatever.  Another hurdle lowered.
(however you will need machinekit to provide mank, to view them on the command line.  Viewing using a browser plugin is of course unaffected )

[John Kasunich]

On Mon, Aug 8, 2016, at 12:52 PM, schoo...@btinternet.com wrote:
> I don't think it will be fruitful to enter into any further debates.

Perhaps not.

>
> However:
>
> >> I see halcmd as something like grep. It runs from the command line,
> >> and its documentation should be available from the command line.
>
> >> But "man halcmd" doesn't work, and that seems to be a policy
> >> decision by machinekit leadership. I simply cannot agree with that
> >> decision. Such is life.
>
> "mank halcmd" DOES work on the command line.

And how is the user to know that the answer is mank?

The need to use mank is not discoverable by a user unless
he happens to read just the right paragraph on just the right
page of the machinekit website.

>
> *'Anything related to machineKit, add a K'** * I did consider the

> feasibility of having an 'interception script' via /etc/alternatives
> for man, to fork machinekit display requests one way and normal man
> pages another. However since there is no Machinekit distro and
> machinekit could be installed on any kind of linux distro, that was not
> going to be achievable without a lot of bother and undoubted breakages.

Is it impossible to generate traditional manpages (viewable by "man")
from the asciidoc sources?

> I don't think typing one extra letter is too bad a compromise. Try it.

It's not typing the letter that's the problem. Its knowing that you
need to type the letter.

You're probably right - neither of us is going to convince the other.



--
John Kasunich
jmkas...@fastmail.fm

[Norbert Schechner]

Hallo @all,

I was reading this and I remembered my first attends to contribute to machinekit ;-)
I agree, that there should be a way to advice the user, that mank is the way to get info, may be even through man machinekit!?

But John,

you have to admit, that documentation has improved a lot on this project and I am sure, that any idea will be discussed and improvements will be incorporated.
I will come back to machinekit, as soon as I can !

Norbert

[Charles Steinkuehler]

On 8/8/2016 12:49 PM, John Kasunich wrote:
>
> Is it impossible to generate traditional manpages (viewable by "man")
> from the asciidoc sources?

Apparently, it is. That's how things came to be the way they are.

We decided to standardize on asciidoc for documentation, and despite
much effort it was not possible to get consistently good results in
man format via automatic conversion, so mank was created.

>> I don't think typing one extra letter is too bad a compromise. Try it.
>
> It's not typing the letter that's the problem. Its knowing that you
> need to type the letter.

I think having stub man pages referring to mank will help a lot with
this. The issue goes from a show-stopper for the user "Where's the
documentation?!?" to a strange nuisance "When will I remember to type
mank first?!?". :)

--
Charles Steinkuehler
cha...@steinkuehler.net

[John Kasunich]

On Tue, Aug 9, 2016, at 08:20 AM, Charles Steinkuehler wrote:
> >
> > It's not typing the letter that's the problem. Its knowing that you
> > need to type the letter.
>
> I think having stub man pages referring to mank will help a lot with
> this. The issue goes from a show-stopper for the user "Where's the
> documentation?!?" to a strange nuisance "When will I remember to type
> mank first?!?". :)

Agreed. And if I forget, the stub will remind me.


--
John Kasunich
jmkas...@fastmail.fm

[Schooner]

Hi,

I think you have not received any replies for 2 reasons.

1)  You have piggy backed onto a thread that has little relevance to your question (whatever it is)

2)  No-one reading your post has any idea what you are trying to do and with what.

I would suggest that that you start a new thread and clearly set out what you are trying to control with Machinekit, which is the main missing element.

BBB is nothing to do with Machinekit, it is just an underpowered ARM board that is popular with reprap users and the like, because it does what they need in a small package..

For a person new to CNC and Linux, it is probably the worst possible platform to start with, as it introduces all sorts of additional complexities and arcaneness.

There are lots of people out there using many different machines and there are lots of stock configurations available as a start.

Until we know what you are trying to do, we can't point you anywhere.

regards


On Monday, 15 August 2016 03:51:20 UTC+1, R. D. Childers wrote:

Thank you for working on the documentation. I create documentation for a living so I am quite appreciative of the effort involved. I am a manufacturing engineer who is just getting started (again/still). I am very excited but I am very lost.  I have purchased a Raspberry Pi and when it looked like it would not suit my needs and then I bought a Beagle Bone Black.  There are books for the standard Beagle Bone Black so I bought several. It looks like I will eventually have to buy a desktop computer to run Lynx. (Understanding what is compatable and why is frying my brain)

My attempts at understanding what to do have been extremely confusing. I love the fact that there exist links to other areas. I get lost regarding what is the core of must haves that I need and how do I determine what to purchase that fits my needs.

I would like a check list. I sat down with John Morris and he wrote out a few things to help me get started but there are a lot of terms that are used and searching those terms on the internet can provide a great deal of information that is not related to my needs.

I would gladly create a video of me bringing up a board and motors and sensors.......I need a guide through the forest.  I have fallen down a number of rabbit holes. I think that there is a great deal of potential to this community and I am willing to contribute. 

I have a link to a number of the things that I would like to do using Machinekit. Is it appropriate to post that link to my Google Doc on this forum?

Thank you.  

R. D. Childers

[R. D. Childers]

I would like to help with the getting started documentation for Machinekit.

[schoo...@btinternet.com]

On 19/10/16 15:13, R. D. Childers wrote:
> I would like to help with the getting started documentation for
> Machinekit.
>

The process is here
http://www.machinekit.io/docs/documenting/contributing-documentation/

Look forward to it

[schoo...@btinternet.com]

Github seems to be subject to problems from this attack at this time
http://www.telegraph.co.uk/technology/2016/10/21/havoc-across-web-as-major-attack-causes-widespread-internet-outa/

I would recommend you do not push / pull or submit anything until it is
clear.

regards