TE
TechEcho
Home24h TopNewestBestAskShowJobs
GitHubTwitter
Home

TechEcho

A tech news platform built with Next.js, providing global tech news and discussions.

GitHubTwitter

Home

HomeNewestBestAskShowJobs

Resources

HackerNews APIOriginal HackerNewsNext.js

© 2025 TechEcho. All rights reserved.

DocBook 5.1: The Definitive Guide (2020)

65 pointsby rdpintqogeogsaaabout 3 years ago

6 comments

kimiabout 3 years ago
Asciidoc and Asciidoctor can produce DocBook, and from DocBook you can do most formats.<p>Working with the DocBook toolchain is rather unpleasant and brittle (depends a lot on the versions), so my company ended up packaging everything in a Docker container <a href="https:&#x2F;&#x2F;github.com&#x2F;l3nz&#x2F;dockbooker" rel="nofollow">https:&#x2F;&#x2F;github.com&#x2F;l3nz&#x2F;dockbooker</a> - this has worked pretty well for many years but now we mostly use Asciidoctor by itself.
评论 #30552141 未加载
评论 #30551812 未加载
评论 #30552198 未加载
评论 #30557872 未加载
评论 #30552584 未加载
zdwabout 3 years ago
I feel like DocBook is in a bad place compared to alternatives - it&#x27;s to esoteric, too hard to write, and then there&#x27;s the fact that it&#x27;s XML.<p>TeX and friends are first class for paper docs and publication, but given their pre-web origins don&#x27;t work well in that medium.<p>Markdown is just too limited and primitive for anything more than a blog post or basic README file - no captions on figures, hyperlinking to headings&#x2F;sections isn&#x27;t formalized, etc.<p>I tend to think that Sphinx + ReStructuredText makes the right balance in terms of publishing targets, and with all of Python, ReadTheDocs, and the Linux Kernel making the same decision, it seems like the right one. Intersphinx is pretty sweet if you have to link multiple sites together.<p>MS Word and Wikis can go die in a fire.
评论 #30551878 未加载
评论 #30552099 未加载
评论 #30551681 未加载
评论 #30554823 未加载
评论 #30551537 未加载
smartmicabout 3 years ago
For software and technical documentation, I recently rediscovered GNU Texinfo. It perfectly fills the gap that the others have left open.<p>Consistent, fairly easy syntax, exports to DocBook, PDF, HTML and can be read interactively from terminal as well.<p>In contrast to markdown|asciidoc|reStructuredText|… and LaTeX, it handles more complex, non-linear documentation very well.<p><a href="https:&#x2F;&#x2F;www.gnu.org&#x2F;software&#x2F;texinfo&#x2F;manual&#x2F;texinfo&#x2F;texinfo.html" rel="nofollow">https:&#x2F;&#x2F;www.gnu.org&#x2F;software&#x2F;texinfo&#x2F;manual&#x2F;texinfo&#x2F;texinfo....</a>
评论 #30554606 未加载
runningmikeabout 3 years ago
Creating books with Jupyterbook gives creating books in markdown endless options. It’s simple but you can create complex interactive books as well. All browser based powered by JupyterLab and building on sphinx. Check <a href="https:&#x2F;&#x2F;jupyterbook.org&#x2F;intro.html" rel="nofollow">https:&#x2F;&#x2F;jupyterbook.org&#x2F;intro.html</a> <a href="https:&#x2F;&#x2F;nocomplexity.com&#x2F;documents&#x2F;jupyterlab&#x2F;intro.html" rel="nofollow">https:&#x2F;&#x2F;nocomplexity.com&#x2F;documents&#x2F;jupyterlab&#x2F;intro.html</a> for a short intro on Jupyerlab
ivanrabout 3 years ago
DocBook has served me very well. For my books I put together an automated publishing workflow that starts with DocBook and produces output for both print and digital (in my case, PDF, EPUB, and HTML). For context, I wrote and published two books (4 editions) with more than a 1,000 pages combined. My goal was always continuous writing and publishing where everything is fully automated.<p>Conceptually, XML is an excellent choice for this sort of thing. If you want to produce a good quality book, you need many features and markup that can support them. For a technically minded person, being able to programmatically inspect and modify the manuscript is awesome.<p>Unfortunately, the tooling, although very capable and very well documented (via Bob&#x27;s free book <a href="http:&#x2F;&#x2F;www.sagehill.net&#x2F;docbookxsl&#x2F;" rel="nofollow">http:&#x2F;&#x2F;www.sagehill.net&#x2F;docbookxsl&#x2F;</a>), is very difficult to use unless you&#x27;re an XML expert already. XSLT really isn&#x27;t a good choice for this sort of thing. That&#x27;s what I had to use because CSS-styling wasn&#x27;t mature enough. These days I&#x27;d start with CSS instead of XSLT.<p>Crucially, I would use a commercial FO processor. I spent a lot of time with Apache FOP and, even though it&#x27;s a great tool, it lacked a number of features that one needed for a professional use. (It may have improved by now, my experience is from a decade ago.) I eventually purchased a licence for Antenna Formatter, <a href="https:&#x2F;&#x2F;www.antennahouse.com&#x2F;" rel="nofollow">https:&#x2F;&#x2F;www.antennahouse.com&#x2F;</a>, which has saved me so much time.<p>You&#x27;re not meant to write XML by hand, but there aren&#x27;t that many great editors out there. I use OxygenXML, which is all right. It&#x27;s expensive. The best thing about OxygenXML is that it supports change tracking. My copyeditor also uses OxygenXML and we have a great workflow that would be impossible to implement in any other way. For me this is the killer feature. A good copyeditor will make thousands of edits to your manuscript. Having an easy way to handle those, respond, and communicate... is key.<p>There are some other interesting tools out there, for example DocBook Compare, which we use to show exactly what changed between two editions. I have some screenshots of what that looks like in this blog post: <a href="https:&#x2F;&#x2F;blog.ivanristic.com&#x2F;2022&#x2F;02&#x2F;bulletproof-tls-and-pki-is-out.html" rel="nofollow">https:&#x2F;&#x2F;blog.ivanristic.com&#x2F;2022&#x2F;02&#x2F;bulletproof-tls-and-pki-...</a><p>To sum up: Do use DocBook. Use OxygenXML to write your books and collaborate with your coauthors and editors. Use Antenna Formatter and CSS for styling. It&#x27;s going to cost you about $2,000 in software licences, but it&#x27;s worth it and it will pay back loads in time saved. I understand that no one will spend this much money for a hobby, but for any sort of professional activity, it&#x27;s a no-brainer.
评论 #30559498 未加载
ameliusabout 3 years ago
Is there anyone who enjoys writing XML?
评论 #30559797 未加载