On 9/10/2011 8:23 PM, Jon Elson wrote: > I just had a very worrisome message from John Thornton about the state > of the documentation, and would like to find out if anyone knows what is > going on? Apparently, Kim Kirwan took upon himself the task of > revitalizing the whole documentation preparation system, but at least right > now the future docs are not in good shape. I have identified 3 areas where > there are serious problems. > <details deleted for brevity> > Obviously, John Thornton has been aware of this for some time, but if > other developers > are not aware of it, I just wanted to make sure everybody knows. I hope > something is > in the works to fix this, but if not, then maybe we need to start > thinking of how to > solve it. > > Jon
Jon et al. I have stayed well clear of the emc2 documentation workflow because I had got my fill of such stuff before I retired. Still, I have notches on my belt for editing major technical documents like IGES (mostly on my own) and STEP (with lots of teamwork) and turning them into electronic documents and in both cases had to deal with similar hodgepodges of source files, image files, and toolchains. If I accomplish nothing else, let me at least get y'all to "go slow." The documentation sources may be in a precarious state but they can be made immeasurably worse through haste (oh the stories I could tell...). At the moment I know nothing of the documentation toolchain introduced with 2.5 but I'm now devoting some of my weekend to figuring it out. For grins, I just built the complete pdf and html documentation pulled from the git master branch following the wiki instructions like any noob. Granted, this was, therefore, 2.6.0~pre but I figured it would be instructive. I watched the build messages marching past and saw them flagging the usual kinds of problems that arise with such a large set of source files, typically broken xrefs and "missing" characters. These just suggest the usual need for some editorial tidying up. I suspect the ToC issue you mentioned will be another tidying up. The latexmath-to-html issue will take a little skull-scratching, but I'll be surprised if it doesn't have a fairly straightforward solution. As for missing sections and/or corrupt sources like your PPMC documentation, it likely will take the content creators to get a handle of the problem. I'd like to think that some fairly mechanical comparison of git sources for 2.4 and 2.5 (and 2.6 for that matter) would help identify where things went, but I'm just blowing smoke 'til I get a sense of the problem. I'll let you know late Sunday or sometime Monday what I ferret out. Regards, Kent ------------------------------------------------------------------------------ Using storage to extend the benefits of virtualization and iSCSI Virtualization increases hardware utilization and delivers a new level of agility. Learn what those decisions are and how to modernize your storage and backup environments for virtualization. http://www.accelacomm.com/jaw/sfnl/114/51434361/ _______________________________________________ Emc-developers mailing list Emc-developers@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/emc-developers
