Re: Markup languages - more on the shortcomings of MS Word
On 27/12/22 10:43, Ed Jaffe wrote: My team uses https://vuejs.org/. At the moment we only build HTML but there are packages to render a multitidue of different formats including PDF, word docs etc. Extensions are written in Typescript or Javascript so there is a massive eco-system to pull from. For many years we used MS Word for our product documentation, but it was just too buggy and cumbersome. Our team now uses MadCap Flare. It's a "best of breed" solution specifically designed for technical documentation. https://www.madcapsoftware.com/products/flare/ We use it to deliver our documentation in three formats: Adobe PDF, HTML, and Eclipse plug-ins that can be used with IBM InfoCenter and KnowledgeCenter (including KC4Z on z/OS) Looks great! It supports DITA which we use for our IBM marketed products that get published on KC. I like that it has extensive build automation including a CLI so integrating into a DevOps pipeline using Jenkins or other build automation is simple. -- For IBM-MAIN subscribe / signoff / archive access instructions, send email to lists...@listserv.ua.edu with the message: INFO IBM-MAIN
Re: Markup languages - more on the shortcomings of MS Word
On 12/26/2022 6:17 PM, David Crayford wrote: My team uses https://vuejs.org/. At the moment we only build HTML but there are packages to render a multitidue of different formats including PDF, word docs etc. Extensions are written in Typescript or Javascript so there is a massive eco-system to pull from. For many years we used MS Word for our product documentation, but it was just too buggy and cumbersome. Our team now uses MadCap Flare. It's a "best of breed" solution specifically designed for technical documentation. https://www.madcapsoftware.com/products/flare/ We use it to deliver our documentation in three formats: Adobe PDF, HTML, and Eclipse plug-ins that can be used with IBM InfoCenter and KnowledgeCenter (including KC4Z on z/OS). -- Phoenix Software International Edward E. Jaffe 831 Parkview Drive North El Segundo, CA 90245 https://www.phoenixsoftware.com/ This e-mail message, including any attachments, appended messages and the information contained therein, is for the sole use of the intended recipient(s). If you are not an intended recipient or have otherwise received this email message in error, any use, dissemination, distribution, review, storage or copying of this e-mail message and the information contained therein is strictly prohibited. If you are not an intended recipient, please contact the sender by reply e-mail and destroy all copies of this email message and do not otherwise utilize or retain this email message or any or all of the information contained therein. Although this email message and any attachments or appended messages are believed to be free of any virus or other defect that might affect any computer system into which it is received and opened, it is the responsibility of the recipient to ensure that it is virus free and no responsibility is accepted by the sender for any loss or damage arising in any way from its opening or use. -- For IBM-MAIN subscribe / signoff / archive access instructions, send email to lists...@listserv.ua.edu with the message: INFO IBM-MAIN
Re: Markup languages - more on the shortcomings of MS Word
MS Word is a great product for it's main use case. I don't consider it a good choice for technical documentation and neither does the Information Developer in my team. There are many better tools out there, some of which are free. Documentation in today's world can be published in many different formats. Text documents, HTML, PDF etc. Documentation should be considered code, which is why markdown is so popular. Documentation should go through the same development pipeline as source code with a pull request and a code review before being committed to a SCM and rendered into product artifacts. MS Word is useless for team collaboration. It's ok for a one person team but doesn't scale. My team uses https://vuejs.org/. At the moment we only build HTML but there are packages to render a multitidue of different formats including PDF, word docs etc. Extensions are written in Typescript or Javascript so there is a massive eco-system to pull from. On 27/12/22 00:54, Charles Mills wrote: I have avoided replying on this thread. It is not my job to shill for Microsoft on a mainframe forum. However, just to get the facts on the record, let me say that I have been composing very complex manuals with included text and generated TODs and indexes in MS-Word for years, and publishing them as PDFs, with 100% success. Charles -Original Message- From: IBM Mainframe Discussion List [mailto:IBM-MAIN@LISTSERV.UA.EDU] On Behalf Of Bob Bridges Sent: Monday, December 26, 2022 6:52 AM To: IBM-MAIN@LISTSERV.UA.EDU Subject: Re: Markup languages - more on the shortcomings of MS Word Once we were done with Christmas morning, my son and his family took off for other Christmas venues and I spent most of the day downloading MiKTeX (an editor for LateX) and reading documentatino. Finding the documentation was a bit of a chore and I'm not satisfied yet that I have everything I'll need, but the web eventually yielded up manuals whose titles, at least, claim they're about LaTeX, LaTeX2e, TeXWorks and MikTeX. I have a lot of reading yet to do. This morning I emailed the Word document to myself and tried saving it as PDF. Turns out Word is awful at that too. It skipped over most of the ToC and jumped from there straight to the beginning of the second chapter, omitting the Intro. I probably won't bother to see what else is wrong with it. -- For IBM-MAIN subscribe / signoff / archive access instructions, send email to lists...@listserv.ua.edu with the message: INFO IBM-MAIN -- For IBM-MAIN subscribe / signoff / archive access instructions, send email to lists...@listserv.ua.edu with the message: INFO IBM-MAIN
Re: Markup languages - more on the shortcomings of MS Word
In fact I did not. Good point. It happens I'm still logged on at the client cite; let's try it there... Nope, same problem. Nevertheless I was hasty to blame Word; it's very possible I just didn't set it up correctly in the .docx format. I know better than to manually set formatting and believe it's the same as defining and using styles, but there may even so be mistakes in my work. Still, though; if I'm going to make that kind of mistake in Word, I think I'm better off using a markup language instead. --- Bob Bridges, robhbrid...@gmail.com, cell 336 382-7313 /* ...the director and the writers keep changing the script. The actors will do a scene, and the director will say, "OK, that was perfect, but this time, Bob, instead of saying 'What's for dinner?' you say, 'Wait a minute! Benzene is actually a hydrocarbon!' And say it with a Norwegian accent. Also, we think maybe your character should have no arms." -Dave Barry, describing his acting debut in "Dave's World" */ -Original Message- From: IBM Mainframe Discussion List On Behalf Of Paul Gilmartin Sent: Monday, December 26, 2022 14:52 Seems more like a problem with mail than with Word. Did you bother to see that the file you received was identical to the file you mailed? --- On Mon, 26 Dec 2022 09:52:16 -0500, Bob Bridges wrote: >This morning I emailed the Word document to myself and tried saving it >as PDF. Turns out Word is awful at that too. It skipped over most of >the ToC and jumped from there straight to the beginning of the second >chapter, omitting the Intro. I probably won't bother to see what else is >wrong with it. -- For IBM-MAIN subscribe / signoff / archive access instructions, send email to lists...@listserv.ua.edu with the message: INFO IBM-MAIN
Re: Markup languages - more on the shortcomings of MS Word
On 26/12/2022 20:52, Paul Gilmartin wrote: On Mon, 26 Dec 2022 09:52:16 -0500, Bob Bridges wrote: ... This morning I emailed the Word document to myself and tried saving it as PDF. Turns out Word is awful at that too. It skipped over most of the ToC and jumped from there straight to the beginning of the second chapter, omitting the Intro. I probably won't bother to see what else is wrong with it. Seems more like a problem with mail than with Word. Did you bother to see that the file you received was identical to the file you mailed? File not saved before email? table of contents was not updated before save? -- For IBM-MAIN subscribe / signoff / archive access instructions, send email to lists...@listserv.ua.edu with the message: INFO IBM-MAIN
Re: Markup languages - more on the shortcomings of MS Word
On Mon, 26 Dec 2022 09:52:16 -0500, Bob Bridges wrote: >... >This morning I emailed the Word document to myself and tried saving it as >PDF. Turns out Word is awful at that too. It skipped over most of the ToC >and jumped from there straight to the beginning of the second chapter, >omitting the Intro. I probably won't bother to see what else is wrong with it. > Seems more like a problem with mail than with Word. Did you bother to see that the file you received was identical to the file you mailed? -- gil -- For IBM-MAIN subscribe / signoff / archive access instructions, send email to lists...@listserv.ua.edu with the message: INFO IBM-MAIN
Re: Markup languages - more on the shortcomings of MS Word
On 26/12/2022 17:54, Charles Mills wrote: I have avoided replying on this thread. It is not my job to shill for Microsoft on a mainframe forum. However, just to get the facts on the record, let me say that I have been composing very complex manuals with included text and generated TODs and indexes in MS-Word for years, and publishing them as PDFs, with 100% success. Charles We seem to share a similar experience. :-) Peter -- For IBM-MAIN subscribe / signoff / archive access instructions, send email to lists...@listserv.ua.edu with the message: INFO IBM-MAIN
Re: Markup languages - more on the shortcomings of MS Word
I have avoided replying on this thread. It is not my job to shill for Microsoft on a mainframe forum. However, just to get the facts on the record, let me say that I have been composing very complex manuals with included text and generated TODs and indexes in MS-Word for years, and publishing them as PDFs, with 100% success. Charles -Original Message- From: IBM Mainframe Discussion List [mailto:IBM-MAIN@LISTSERV.UA.EDU] On Behalf Of Bob Bridges Sent: Monday, December 26, 2022 6:52 AM To: IBM-MAIN@LISTSERV.UA.EDU Subject: Re: Markup languages - more on the shortcomings of MS Word Once we were done with Christmas morning, my son and his family took off for other Christmas venues and I spent most of the day downloading MiKTeX (an editor for LateX) and reading documentatino. Finding the documentation was a bit of a chore and I'm not satisfied yet that I have everything I'll need, but the web eventually yielded up manuals whose titles, at least, claim they're about LaTeX, LaTeX2e, TeXWorks and MikTeX. I have a lot of reading yet to do. This morning I emailed the Word document to myself and tried saving it as PDF. Turns out Word is awful at that too. It skipped over most of the ToC and jumped from there straight to the beginning of the second chapter, omitting the Intro. I probably won't bother to see what else is wrong with it. -- For IBM-MAIN subscribe / signoff / archive access instructions, send email to lists...@listserv.ua.edu with the message: INFO IBM-MAIN
Re: Markup languages - more on the shortcomings of MS Word
If you will be writing your own macros, I'd suggest looking at expl3 (LaTeX 3) and friends; still experimental, but quite handy. -- Shmuel (Seymour J.) Metz http://mason.gmu.edu/~smetz3 From: IBM Mainframe Discussion List [IBM-MAIN@LISTSERV.UA.EDU] on behalf of Bob Bridges [robhbrid...@gmail.com] Sent: Monday, December 26, 2022 9:52 AM To: IBM-MAIN@LISTSERV.UA.EDU Subject: Re: Markup languages - more on the shortcomings of MS Word Once we were done with Christmas morning, my son and his family took off for other Christmas venues and I spent most of the day downloading MiKTeX (an editor for LateX) and reading documentatino. Finding the documentation was a bit of a chore and I'm not satisfied yet that I have everything I'll need, but the web eventually yielded up manuals whose titles, at least, claim they're about LaTeX, LaTeX2e, TeXWorks and MikTeX. I have a lot of reading yet to do. This morning I emailed the Word document to myself and tried saving it as PDF. Turns out Word is awful at that too. It skipped over most of the ToC and jumped from there straight to the beginning of the second chapter, omitting the Intro. I probably won't bother to see what else is wrong with it. --- Bob Bridges, robhbrid...@gmail.com, cell 336 382-7313 /* Do right, and God's recompense to you will be the power of doing more right. Give, and God's reward to you will be the spirit of giving moreLove, and God will pay you with the capacity of more love -F W Robertson */ -- For IBM-MAIN subscribe / signoff / archive access instructions, send email to lists...@listserv.ua.edu with the message: INFO IBM-MAIN -- For IBM-MAIN subscribe / signoff / archive access instructions, send email to lists...@listserv.ua.edu with the message: INFO IBM-MAIN
Re: Markup languages - more on the shortcomings of MS Word
Once we were done with Christmas morning, my son and his family took off for other Christmas venues and I spent most of the day downloading MiKTeX (an editor for LateX) and reading documentatino. Finding the documentation was a bit of a chore and I'm not satisfied yet that I have everything I'll need, but the web eventually yielded up manuals whose titles, at least, claim they're about LaTeX, LaTeX2e, TeXWorks and MikTeX. I have a lot of reading yet to do. This morning I emailed the Word document to myself and tried saving it as PDF. Turns out Word is awful at that too. It skipped over most of the ToC and jumped from there straight to the beginning of the second chapter, omitting the Intro. I probably won't bother to see what else is wrong with it. --- Bob Bridges, robhbrid...@gmail.com, cell 336 382-7313 /* Do right, and God's recompense to you will be the power of doing more right. Give, and God's reward to you will be the spirit of giving moreLove, and God will pay you with the capacity of more love -F W Robertson */ -- For IBM-MAIN subscribe / signoff / archive access instructions, send email to lists...@listserv.ua.edu with the message: INFO IBM-MAIN
