I use it all the time. When I can’t get the right search term to find something in the docs, I can often find direction in the handbook.
Oh, and I’d absolutely pitch in to see it updated.
1 Like
Zed and I are having a conversation about how to make a revised edition available in various formats. We’ve hit a bottleneck. I’m hoping somebody (maybe somebody named Zarf) will have a suggestion. So here’s the situation, in a nutshell:
Zed has ported the existing version of the Handbook into markdown format (.md files) as preparation for converting the chapters into html web pages. Meanwhile, I’ve started doing revisions in LibreOffice, a word processor.
It would be way too much trouble for Zed to take my revised version (after I finish it) and convert it all to markdown again, starting from scratch. But if I do my revisions in markdown, there’s no way for me to convert it back into .rtf or even into a good-looking PDF.
I have a plugin to my text editor (Notepad++ for Windows) that will convert .md to PDF, but it doesn’t look the way I’d like it to. In order to edit the PDF I’d have to pay Adobe $20 a month for Acrobat Pro. That would also allow me to convert the PDF back to .rtf – but that could easily be as much work as Zed would put into converting my revised .rtf into .md again, because the conversions are likely to be filled with little problems.
Going the other direction, LibreOffice will export in XHTML, but it does a really crappy job of it.
There are other snarfles to do with working in a text editor, such as the absence of curly quotes, but in a pinch I could deal with that. The real issue is that it appears markdown is pretty much a one-way street. I don’t care for the idea of doing a revised version and not being able to get it back into word processor form. But I know some people would love to have an HTML version, and if I do the revisions in my word processor, the HTML ain’t gonna happen.
I hope I’ve described the conundrum adequately. Suggestions would be very welcome.
1 Like
Pandoc can convert (both directions) between markdown and .docx, .odt and HTML. (As well as epub and many others.)
It also supported reStructuredText, which is a less simple alternative to markdown but also supports footnotes and other things.
The conversions won’t be perfect, but it would be worth giving a try.
3 Likes
Thanks for the suggestion. I’m trying it, but not getting anything but gibberish or failure. I’ve used command line programs in the past, so I know the basics, but if there’s a trick to it, I’m not finding the trick in the documentation.
Markdown isn’t actually relevant if the canonical source is going to be an OpenDocument file. The real target is HTML. Markdown was for ease of editing and source control. The toughest requirements is that I need something that can retain indication of the beginnings and ends of game output examples and code samples and maintain the exact whitespace, down to hard tab characters, of the latter.
I’d probably have to write something to traverse the XML to get all that right.
LibreOffice saves perfectly to .odt. That’s an OpenDocument file. Is it something you could use?
yeah. It’ll be obnoxious to get all the details right, but it’s doable.
I use markdown as the canonical source for spec documents (e.g. The Treaty of Babel .) But that has very minimal formatting needs, and even then I have to customize the md>>html converter a bit. I wouldn’t try to do a book that way.
1 Like
Turns out there’s an online source (convertio) that can convert .odt to html. I just tried it with one chapter, and the formatting is pretty darn good. However: A standard Windows copy/paste command loses the Tab characters. They’re visible in the html display in a browser, but copying the text loses them. There may be a way around this, but I’ll have to research it further tomorrow.
1 Like
I have Adobe Acrobat Pro. (I get an educational discount since I still have the certification.)
I could possibly do the conversion for you if you would like me to try.
Thanks for the offer. We may take you up on that. But there would be more to it than file conversion. There would also be cleanup. It could get laborious.
At the moment I’m pursuing a different idea.
1 Like
I know someone who wrote a book using the LyX document processor, converted it to HTML using Elyxer, and converted the HTML to e-book formats using Calibre.
1 Like
It’s actually possible to make professional-looking books/PDFs from an HTML file (and so from Markdown too) by using the “print to PDF” option in the browser.
There are some CSS properties that make it possible to set the page size and the like. They’re not all currently supported by browsers, but JavaScript libraries exist to emulate them, such as paged.js.
You can search “CSS paged media” on the web to find other libraries/softwares that do that.
1 Like
I hadn’t considered that. I don’t see this command in the Firefox menu, but I haven’t looked very hard. The issue is not creating a PDF, however. The issue is creating a PDF that looks right. That requires Acrobat Pro.
1 Like
I’m not sure I get it. With the right CSS (and the right JavaScript libraries to fill the gaps from the browser), the PDF should look right by default. It’s the same with, say, LibreOffice: when you export to a PDF, you directly get a good-looking PDF, without needing to use Acrobat Pro.
Although I understand it can be difficult to get the CSS right.
(Disclaimer: I haven’t actually produced a book or a PDF by using web technologies.)
It should … but it may not. There’s many a slip twixt the cup and the lip.
To explain in a bit more detail, I want to revise and update the Handbook in LibreOffice. Zed wants to import the chapters as browser html files in a website he’s planning. So far, he has been using markdown. This works, but he has been using the current version of the Handbook, not the revised version (which doesn’t exist yet). He doesn’t want to start over, turning the revised version into markdown files, because that’s a lot of work. So we’re trying to find a way for me to work in LibreOffice (which will indeed export good PDFs) while performing some sort of magic translation from the LibreOffice file(s) to nice-looking html files. He wants to be able to link to (and from) the Handbook chapters. Inserting links isn’t hard, but as a whole, preparing the html files for his website is complex. We’re trying to simplify that. One idea would be for me to do the revisions directly in his markdown files, but that turns out not to be practical, because there’s no way to back-port from markdown to LibreOffice word processor files. So if I do the revisions in markdown, we have the problem of converting the markdown or html files not just into PDF (which may be imperfect) but also into .odt or .rtf. The reason for that part of the back-port is that there are one or two people, and maybe more, who need the word processor file. For instance, to translate it into Italian.
Basically, we’re trying to change the engines of an airplane while in midair, if you see what I mean.
1 Like