Does anyone here use docbook? - Page 1
Forum section: electronics / projects

author: coppice
author_rank: Super Contributor
timestamp: September 19, 2024, 06:37:58 pm
content: I have used docbook tools professionally in the past for producing large scale technical documentation, but those tools are expensive. I am looking around for open source tools I might use for personal work. I can't seem to find anything with so much momentum it really stands out. Does anyone have an recommendations.

author: voltsandjolts
author_rank: Unknown
timestamp: September 19, 2024, 06:46:43 pm
content: cross-ref:https://www.eevblog.com/forum/projects/what-programs-do-you-use-for-creating-technical-documents/

author: Doctorandus_P
author_rank: Super Contributor
timestamp: September 19, 2024, 06:51:34 pm
content: I use exclusively open source software, and then donate to projects I like. Sometimes monetary units, sometimes time.docbook is apparently an open standard, but that does not say much about the tools. XML is also not very remarkable. Libre Office documents are zipped XML. (Just open it in any archive manager). I use LibreOffice only very rarely myself, even though it's installed by default on my Linux box. I prefer something lean and simple, but with just enoug power to make it do useful things. Lately I've been looking a bit into asciidoc and it appears to be a quite good fit for the sort of things I do. You write it in any text editor, and you can compile it into other formats such as HTML, PDF, epub and a few others.Food find from voltsandjolts. In that thread asciidoctor (the compiler for the asciidoc format) can also output docbook. There is also an asciidoc plugin for firefox, that re-reads and reformats the text each time you save the flat text file in your text editor.

author: voltsandjolts
author_rank: Unknown
timestamp: September 20, 2024, 10:55:51 am
content: I circle this problem myself every now and again, but always seem to fall back on the lowest-common-denominator we use at work: MS Word. I give up on getting an engineering team to agree on anything else.Given the choice, for technical documentation I would probably be looking at choosing between:AsciiDocasciidoctor- see the RP2040 datasheet as an example. This can generate docbook so might interest you more.https://github.com/bodiam/awesome-asciidocExample: Here is the AsciiDocsourceforPro Git 2nd Edition. Processed using AsciiDoctor.reStructuredTextrestructuredtext- used for python documentationhttps://github.com/ralsina/rst-cheatsheet/tree/masterhttps://github.com/vscode-restructuredtext/vscode-restructuredtexthttps://rst2pdf.org/

author: pardo-bsso
author_rank: Frequent Contributor
timestamp: September 24, 2024, 03:51:21 pm
content: I used rst2pdf quite long ago but moved to Pandoc. I like it.

author: Daixiwen
author_rank: Frequent Contributor
timestamp: September 26, 2024, 08:31:05 am
content: At my day job we are currently evaluatingTypstfor technical documentation and we like it a lot.It's the same principle than LateX, but with a much easier to use syntax (similar to Markdown) and still much control over the layout. I managed to create a template that looks exactly like our MS Word templates in less than a day.If you use VS Code, installation is very easy because it exists as a plugin. You can then edit your documents and get a preview in real time directly from VS Code.It is based on markdown but you can also use variables and functions on the document itself to generate content, import data from csv files, and much more.There are lots of plugins available, including things likewavedromto create time diagrams, generate figures from code... I think it's really a step up from MS Word for technical documentation. And as its a text based format, it is also very friendly with source control tools.

author: Doctorandus_P
author_rank: Super Contributor
timestamp: September 26, 2024, 10:47:15 am
content: I had a very brief look at Typst just now, and the first thing I noticed is that it apparently only generates pdf output. I very much dislike PDF. It was designed to be put on rectangular sections of dead trees, and nothing else. For example try to copy some text from a pdf (especially when it has columns of text) or extract IC pinout information to draw a custom symbol for your favourite EDA packageA hard stop for me is the commercial aspect of Typst. It's not the money, but I will never give some external party power over what I am going to do with my own documentation over the coming 50 years. Companies get bought or go broke, policies change etc. The hottest breathing dragon in the last few years is software companies forcing everything into "the clouds". It's not for your benefit. It's to get more control over your data.Edit: I just noticed that at least the compiler of Typst is open sourced. That makes my argument a lot less sever, but I have not looked into further details.With asciidoc you can have various output formats. It can do PDF, but also HTML and build complete websites in it (Mostly static websites, It's not fit for dynamic content). I think it supports some other output formats (rich text?) too, but I have not looked into that yet. With an open source application you also always keep absolute control over your own data. It's easy to for the whole project as a backup, so even if the whole asciidoc project collapses, you can still go on and continue using it until all computers have turned into grey dust. And with a copy of the whole build system, you are at least able to fix bugs (or hire someone else to fix bugs) if they ever show up.A very different, but also interesting, thing is Jupyter. It's a much more dynamic environment, in which notes and tables can be combined with software to create dynamic content such as graphs. I think it can also do things such as pull in data from SCPI / IVI instruments, and then do post processing. It's not matlab, but it has similar capabilities, and as it runs on python, you can plug in all sorts of libraries. But I never used it myself. It's a bit too big and "advanced" for my taste.

author: bd139
author_rank: Super Contributor
timestamp: September 26, 2024, 11:09:27 am
content: Tried all this stuff. End up back on LaTeX every time.Once you nail down .sty and structuring complex documentation it's 10x faster and more reliable than anything else.I've got it glued into a complex data collection pipeline that pulls data out, processes it in R then combines it into documentation. All from a Makefile.I am looking at Quarto though which aligns to some technical concerns I havehttps://quarto.org

author: coppice
author_rank: Super Contributor
timestamp: September 26, 2024, 01:56:05 pm
content: Quote from: Doctorandus_P on September 26, 2024, 10:47:15 amWhat commercial aspect did you see? From a quick scan the whole project seems to be Apache licenced, which is very permissive. The big issue with adopting something like this seems to be whether it can gain enough momentum not to fade away, and leave you in the lurch.

author: Doctorandus_P
author_rank: Super Contributor
timestamp: September 26, 2024, 05:02:07 pm
content: Before you wrote that I already noticed my fingers typed to quick and added an edit to my previous post. What triggered my annoyance was the "payment options" before I even knew what the project was about.

author: abeyer
author_rank: Frequent Contributor
timestamp: September 27, 2024, 06:26:55 pm
content: Quote from: coppice on September 26, 2024, 01:56:05 pmThe compiler is apache licensed... so you can install and use it locally like you would latex or similar tools, but you don't get the gui editor that way. I believe the web app with the multi-user collaborative editor is strictly commercial (though free for some limited use) and doesn't have source available.