Some guidelines for the book

[tommai78101]

1. Write a tech book that's around 100 pages in total.
2. Tech books tend to be outdated quickly, so it needs an iterative roadmap.
3. Don't do it like a "recipe book".
4. Consistency is key.
5. Never put opinions in the book.

[legends2k]

Great list @tommai78101. Might I add

6. Use an open format like markdown to lower contribution bar (improving contributions possibilities)

Tools like Pandoc convert .md to .docx in a jiffy so should be a win-win to move to markdown.

[tommai78101]

@legends2k Do we have available tools to convert docx back to Markdown, so that I can create a base file?

A base file refers to a file where I can use as the source, to convert to multiple formats, like DOCX, PDF, EPUB, etc.?

Currently, it's DOCX -> PDF, EPUB, so if I have the base file MD, then I can do MD -> DOCX -> PDF, EPUB, etc.

[OvermindDL1]

Drive-through comment, but you might think about ReST (Restructured Text) instead of markdown. It has a similar syntax to markdown, it's much older than markdown, it's also supported by pandoc (any many other things), and it has significantly greater formatting capabilities than the comparably simple markdown, which is very useful for actual documentation.

Though if you do use pandoc you can actually mix and match all you want...

Pandoc can also output PDF and EPUB as I recall.

[tommai78101]

@OvermindDL1 I can use pandoc, but what I wanted to avoid is rewriting my docs to accommodate for the new formatting changes.

I'm pretty sure I can't just copy/paste my contents of the DOCX file into pandoc, and it would all be the same. I need to make sure that the contents in pandoc is very close to what I'm expecting from the DOCX, including the text layout of the footnotes, the citations, table of references auto-generation, table of figures for the images and the image captions, the Appendix auto-generation, and the page-break layout consistencies.

If there is a DOCX -> ReST or Markdown, or some common text formatting support, then I can look into supporting various ebook formats.

And it's because of that, I included the DOCX and the PDF.

[OvermindDL1]

Well there definitely won't be a docx->markdown converter for what you want as markdown has no concept of things like footnotes or citations or reference table generation, all of which ReST has.

However pandoc does state it can convert from docx to ReST, I've never attempted it as I avoid poor formats like docx (why on earth would anyone use docx over, say, LaTeX?! horrible format...) so I cannot attest to it's quality, but a quick google search shows a variety of instructions on how to do so. Here's some of the more interesting links I found but didn't go through in depth:

https://peintinger.com/?p=365 https://pandoc.org/ https://pypi.org/project/rstdoc/

Optimally I'd absolutely use latex for a document handling format, it can natively export to about anything and it's more powerful than anything else (it puts docx to absolute shame in what it can do), and although it's very well known in some industries (such as educational, which is the industry I'm in) it's less well known in the overall public even though it's one of the oldest and most powerful formats, that's why I tend to encourage ReST for document intermediary formats as it has the simplicity of markdown while still being "useful enough" in most cases (especially as it's extensible with plugins as the syntax has native support for plugin syntaxes).

[tommai78101]

Thanks for the links. I still want to keep the auto-generation of citations and references as they are the result of endless research on my part.

[OvermindDL1]

Thanks for the links. I still want to keep the auto-generation of citations and references as they are the result of endless research on my part.

I'm really trying hard not to push LaTeX but it really sounds like you want LaTeX, lol. ^.^;

But yeah, you definitely don't want markdown from the sounds of it, ReST would likely work fine.