On 11/17/2011 6:16 AM, Kim Kirwan wrote:
Hi John, Hi all,
Thanks for this opportunity to clarify a few things.
Of the 13 chapters alleged to be missing, 9 of them should be
the HAL drivers that I moved to the HAL Manual. Well, 8 anyway.
The 9th one was the m5i20 driver, which has been officially
deprecated for some time in favor of hostmot2. So, since this
is a major revision, I either deleted the m5i20 chapter, or,
more likely, just left it off the HAL Manual processing list.
Of course, it's still present in v2.4 for those that want it.
So 13 less 9 leaves 4.
Some of those 4 may also be HAL-related chapters that I thought
would be better grouped in the HAL Manual. I thought that the
Integrator Manual would be improved by having a greater .
concentration on integration, and less on HAL, which we have a
separate manual for. And that the HAL Manual would be improved by
having more HAL chapters in the HAL Manual and fewer elsewhere.
If I did not get this right, or if I made errors in chapter
order, selection, arrangement, etc., I would be happy to hear
any specific suggestions on how to improve things.
Now true, there is an argument for having Integrator and HAL in
one manual, and since I made these changes, there has been some
discussion of dropping the HAL manual entirely and putting
everything HAL in the Integrator Manual. I confess that I am not
fond of this idea, for three reasons.
First, the HAL subsystem is one of the most successful and
popular parts of EMC2, sometimes even used by itself, without
the rest of EMC2, and I believe that both HAL and EMC2 are better
served by having a separate HAL Manual.
The focus of the HAL manual *was* on using HAL standalone.
Second, I believe that keeping the two manuals separate makes
it easier for new users to get started, since there is a clearer
line of separation between subjects covered in the manuals.
And it reduces the page count, which makes it less intimidating
for newbies to dive in. The most recent build of the 2.5 docs
that I have (Nov 06) says: Integrator, 190 pages; HAL 167 pages;
User, 191 pages. So if Integrator and HAL were combined, that
is a straight total of 357 pages, which would probably come in
(with some pages saved) maybe around 330-340 pages. Quite a bit
to throw at a newbie all at once.
Actually it makes it harder for a newbee to find things (I know this
from experience) when spread across more than one manual. Now to setup
and configure your machine you have to bounce back and forth from the
HAL manual to the Integrators manual which makes trying to configure a
machine a horrible nightmare for a new person. The page count makes no
difference when you can't search a pdf for the information you need
because it is in some other pdf.
Third, such a large change (getting rid of the HAL Manual)
would certainly require approval, or taking a vote, or some
such, and I was not interested in making large changes, only
three small ones, which I'll detail later in this post.
Seems like moving chapters out of the Integrators manual should have
been voted on before doing it as everyone that has responded so far
prefers the previous layout. Seems like your the only one that prefers
the integrators manual to be chopped up and 1/2 the integrators
information to be in the HAL manual. I would like to move them back to
the Integrators manual before 2.5 hits the street.
But, having said all this, if the customers say that the
Integrator and HAL Manuals should be combined, I'll certainly
offer to help.
As far as the 5 chapters in the wrong section (compared to
how it was before, I presume?), if you could be more specific,
maybe I could tell you what the intent was?
Well you moved vital information for integrators about the drivers out
of the integrators manual but left all the examples for the drivers in
the integrators manual and put them in the Classicladder Section.
John, I agree with you that if I have duplicated chapters
across two manuals, I should not have done that, good catch,
thanks! That may have been me taking extra care not to delete
anything while copying and then forgetting to delete (from
the processing list) what I should have deleted?
In any case, I will be glad to help you (or anyone) work on
this, although I admit that my time is now more limited than
during the months when I was looking for work and was doing
docs editing pretty much full-time.
As far as the three changes that I wanted to make, after I
had fixed as many typos and grammar errors as I could find,
and was beaten into submission by AsciiDoc problems that I
could neither fix (above my pay grade) nor find a workaround
for, I began to look around for what I thought were three
small improvements that I *could* do that were the most needed.
I settled on these:
1) Try to improve Integrator& HAL Manuals organization.
This has already been discussed above.
2) Get the HTML docs to match the PDF docs.
Was there some reason to have the overleaf image and overleaf page and
the copyright and the glossary repeated 5 times in the html documents?
It only adds confusion to them and makes the page even longer than
before which makes navigation more difficult especially on a laptop.
There is no reason for the HTML docs to EXACTLY match the pdf's that I
can think of.
Many big open source projects offer their documentation in
two or more formats, but it's always the same content/order.
Our content/order was different, which I thought was due to
the combination of years of neglect and the obscure scripting
method of generating the HTML.
Not really, it was from years of hard work trying to present the HTML
in a logical order. I agree there was room for improvement in the
organization of the HTML docs. Seems we still have the obscure
scripting method of generating the HTML and pdf's.
3) Add support for Spanish and German docs.
This seemed to me to be no big deal, since we already had
the French docs. We already had a request for the Spanish docs,
and I anticipated a request for the German docs. So I framed
them up in English and left them for their translators. I also
updated the French docs with English changes where they had
suffered from years of neglect and had fallen behind. (My
apologies to the French translators for the places that I
tried Google translate and succeeded in offending them.)
Indeed, I offer here an apology (and my thanks) to anyone
who has worked on the documents and was annoyed in some way
by my changes. I assure you, I did not delete anyone's
contributions, I gratefully built upon them.
If my changes are incomplete, in error, etc., let's talk
about what (specifically) needs to be fixed. I welcome
editing assistance from anyone who would like to help.
Why was there no talking before deleting chapters from the Integrators
manual?
Are you editor in chief now?
Sorry I've been away from it for awhile, I had paused my
editing until the Asciidoc problems got sorted out, and
then work came along.
Kim
Even though I am very upset about you deleting the drivers chapters
from the Integrators manual without some discussion in the EMC
community and developers, I really do appreciate all the work you did
on the manuals especially adding the Spanish and German docs and the
ton of typo and grammar fixes.
The more I think about the PDF manuals the only thing that makes sense
is to have one PDF. The page count is irrelevant in todays high speed
world. Being able to search the ENTIRE manual is so huge of a benefit
that it makes no sense to have the separate PDF documents. Next huge
benefit is being able to link to anywhere in the documents, then
jepler would not be sore at me any more... I think this should be a
goal to complete before 2.6 is release.
John
On 11/16/2011 07:19 AM, John Thornton wrote:
I downloaded and checked the Integrators manual and there are 13
chapters that are missing and 5 chapters that are in the wrong section,
some chapters duplicated from other Manuals, chapters out of order...
this can be fixed and should be before 2.5 is released. Duplicating
chapters in different manuals is *very confusing* to a new user and
should be avoided!
John
On 11/15/2011 11:56 AM, Sebastian Kuzminsky wrote:
On Nov 15, 2011, at 10:23 , Jon Elson wrote:
So, am I seeing stale cached copies, or are the hardware driver docs
still missing from
the PDFs? Somebody seemed to be saying they were now there, or maybe I
was misinterpreting.
Ah yes, I think you're right, some of the docs at
linuxcnc.org/docs/2.5 are stale. There we have the following files:
EMC2 Getting Started (fresh)
EMC2 User Manual (fresh)
EMC2 Integrator Manual (fresh)
EMC2 Developer Manual (fresh)
EMC2 Manual Pages (fresh?)
HAL User Manual (stale)
The HAL User Manual was recently renamed, maybe that's why it's stale?
The docs from the buildbot are all fresh (and all the new languages
are available):http://buildbot.linuxcnc.org/doc/
For example, the pdfs from the last 2.5 build is here:
http://buildbot.linuxcnc.org/doc/v2.5_branch/v2.5.0-pre2-170-g05f6a45/pdf/
Here's the new renamed EMC2 HAL Manual:
http://buildbot.linuxcnc.org/doc/v2.5_branch/v2.5.0-pre2-170-g05f6a45/pdf/EMC2_HAL_Manual.pdf
That PDF includes "Section 2: Hardware Drivers", which includes Mesa
and Pico and all(?) the others.
------------------------------------------------------------------------------
All the data continuously generated in your IT infrastructure
contains a definitive record of customers, application performance,
security threats, fraudulent activity, and more. Splunk takes this
data and makes sense of it. IT sense. And common sense.
http://p.sf.net/sfu/splunk-novd2d
_______________________________________________
Emc-developers mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/emc-developers
------------------------------------------------------------------------------
All the data continuously generated in your IT infrastructure
contains a definitive record of customers, application performance,
security threats, fraudulent activity, and more. Splunk takes this
data and makes sense of it. IT sense. And common sense.
http://p.sf.net/sfu/splunk-novd2d
_______________________________________________
Emc-developers mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/emc-developers
