John, I can sympathize, and I don't think you're out of touch. One would think that programmers, whose profession calls for maximizing indirection, would be most apt to leverage template capabilities of a word processor in order to accomplish the same. However, I've come to learn that not everyone has an appreciation for or an understanding of page layout fundamentals, without which a word processor apparently is not much more than a glorified typewriter to some.
I began with X-Acto knives and a light table before being able to use PageMaker and, then, InDesign. So, I probably view discussions like this one from a slightly different perspective than most. Today, expectations of publishing require multiple formats, multiple delivery vehicles, et cetera. Principles of Ops is no exception. PDF is great for some things, not so for others. Likewise with HTML. Same goes for two-column versus one-column. Give me two-column in PDF, if my computer monitor is tall enough, or on a printed sheet of paper. But, I'd like one-column in a small, off-to-the-side desktop web browser window or in Safari on my iPhone, please. What matters most is the content. How it is formatted and delivered is secondary and, ideally, adaptable to varying needs. I would think that this is nearly universally understood. Weighing-in on some of the opinions expressed recently: I believe Principles of Ops should be no more than what it is, content-wise. Even moving the examples of instruction usage from the appendix to a separate document makes sense to me. I agree with others that the wordy nature of instruction descriptions in paragraph form can be cumbersome and not always easy to follow. However, that really is a formatting issue and not a content issue. That same content could be expressed in the form of a bulleted list, table, et cetera. However, such more graphical formats can all carry the curse of impreciseness and ambiguity that doesn't accompany well written sentences. I've learned that I simply need to read those sentences and paragraphs very, very carefully! I suspect, bringing docs such as Principles of Ops "into the internet age" is probably a massive enough undertaking that it is difficult for IBM to make a good business case to do so. So, I am very much intrigued by the notion of an open source project. Regards, Doug Watkins -----Original Message----- From: IBM Mainframe Assembler List [mailto:[email protected]] On Behalf Of John McKown Sent: Monday, November 17, 2014 8:10 AM To: [email protected] Subject: Re: Redesigning the Principles of Operation Manual On Mon, Nov 17, 2014 at 1:51 AM, Bernd Oppolzer <[email protected]> wrote: > BTW: > > I build the handouts for my technical classes and other documentation > using a special kind of XML, and from that XML I generate HTML, if > needed, or other representations of the documentation (at the moment I > generate ONLY HTML and do printed representations using a browser and > a PDF generating printer driver, which works pretty well). > I do something similar, for truly large documents. I use XMLMind XML Editor, which has a lower function, but cost free, "personal edition". I also might use LaTex or Kile. But, honestly, I don't do much that requires anything beyond simple use of LibreOffice's word processor. IMO, there is a definite difference between a word processor, document processor, and layout (like a magazine or newspape) processing. http://www.xmlmind.com/xmleditor/ <quote> XMLmind XML Editor is a strictly validating, near WYSIWYG, DocBook <http://docbook.org/> editor, DITA <http://dita.xml.org/> editor, MathML <http://www.w3.org/TR/MathML2/> editor, XHTML <http://www.w3.org/TR/xhtml1/> editor, XML <http://www.w3.org/TR/xml/> editor. Because XMLmind XML Editor is highly extensible, it may be also be used to create documents conforming to your own custom schema. Its users are generally technical writers who need to author large, complex, modular, documents. </quote> I will now insert my whine about how "good enough" (MS Word) has basically driven out "excellent", at least for businesses. I've had others in my group basically say that if MS Word can't do it, then it just doesn't need to be done at all. And they don't even use MS Word "properly" (they just do ad-hoc paragraph and character formatting, instead of using any kind of "template" so that it is easy to change something, say font, in one place and have that affect the entire document appropriately. I finally gave up after I went though our D.R. documentation and "cleaned up" everything then had the next person _refuse_ to even consider keeping it up. I guess that I'm just out of touch with current reality. > > AFAIK, there are other "standard" XML formats to do such things, maybe > one is called BookDoc. > > Using XML, you can do any kind of markup you want. > > -- The temperature of the aqueous content of an unremittingly ogled culinary vessel will not achieve 100 degrees on the Celsius scale. Maranatha! <>< John McKown The contents of this e-mail are intended for the named addressee only. It contains information that may be confidential. Unless you are the named addressee or an authorized designee, you may not copy or use it, or disclose it to anyone else. If you received it in error please notify us immediately and then destroy it
