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
Re: Markup languages
TeX is the underlying language. I believe that most people use a document development environment with an editor and preview facility. Some of the available environments can automatically download required packages from CTAN. It is possible to generate a PDF without an intermediate DVI file. I'd start by looking at MiKTeX, TeX Live and TeXworks, or browse CTAN. -- 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: Thursday, December 22, 2022 6:38 PM To: IBM-MAIN@LISTSERV.UA.EDU Subject: Re: Markup languages I got quite a few nominations from the two forums where I posted this question, and it's early days to say I've settled on one, but currently I'm looking hard at LaTeX. I found a tutorial on it at javatpoint.com, but that was written by a non-native-English writer (maybe he a Slav?, guessing by his odd use of definite articles) and there are some phrases in there I can't parse with confidence. I imagine whatever documentation comes with the download will be clearer. But it seems there are multiple pieces I need to fetch. I get the impression that TEX is the actual markup language, and LaTeX is ... what? A series of extensions to TEX to allow it to do more? And I need a program that will convert my text and markup codes to a printer-ready document, and/or to a PDF file. And most people use a text editor specifically dedicated to working with LaTeX; various options for that last are mentioned. Do you have any specific recommendations? Because I think I'm about ready to download and experiment. --- Bob Bridges, robhbrid...@gmail.com, cell 336 382-7313 /* A person reveals his character by nothing so clearly as the joke he resents. -G C Lichtenberg */ -Original Message- From: IBM Mainframe Discussion List On Behalf Of Seymour J Metz Sent: Thursday, December 22, 2022 08:39 My preference, alas, is dead: BookMagager BUILD/MVS (or VM), which is built on BookMaster and DCF. Lacking that, I make do with LaTeX, which I find powerful but clumsier that the tools built on Script. I make extensive use of nested bulleted and numbered lists, and when I attempt to copy an entry to a different list, word garbles the markup horribly. Is there an equivalent to the reveal mode in word pervert that would allow me to correct that bug? The best that I've been able to come up with is to copy the entry to notepad and then copy from notepad. I would recommend a LaTeX environment, e.g., MiKTeX, TeXworks. Check out resources at CTAN. -- 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
I doubt it, since mark was primarily interested in XEDIT compatibility. Similarly, I don't expect to see a chart comparint e.g., ooRexx, Regina, to KEXX. -- Shmuel (Seymour J.) Metz http://mason.gmu.edu/~smetz3 From: IBM Mainframe Discussion List [IBM-MAIN@LISTSERV.UA.EDU] on behalf of Jeremy Nicoll [jn.ls.mfrm...@letterboxes.org] Sent: Saturday, December 24, 2022 3:07 PM To: IBM-MAIN@LISTSERV.UA.EDU Subject: Re: Markup languages On Fri, 23 Dec 2022, at 12:51, Seymour J Metz wrote: > emacs > THE > vi > ... I've never used either emacs or vi and don't much want to have to learn another text editor's command set. Regarding THE, is there a list anywhere of what the differences between it and Kedit are? Wading through the THE documentation looking at each command is tedious, and it's not helped by finding out that some things are labelled "(not implemented)". > You may have my copy of TSPF when they pry it out of my cold, dead > fingers. I suspect that actually getting it from your estate might be tricky -- Jeremy Nicoll - my opinions are my own. -- 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
