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