Tools to generate documentation of software protocol - Page 1
Forum section: electronics / projects

author: ricko_uk
author_rank: Super Contributor
timestamp: April 29, 2022, 01:56:10 pm
content: Hi,is there some software to quickly generate the documentation for a serial communication protocol?I already have all the command codes, message length, payload details, command description etc in Excel but now want to make a proper manual for it nicely formatted for each command.I can obviously make in MS Word but - with hundreds of commands - would be tedious. So I was wondering what the best way and the best tools to create the documentation quickly are.Many thanks

author: metrologist
author_rank: Super Contributor
timestamp: April 29, 2022, 02:44:49 pm
content: Consider XML database for the content and XML editors/publishing systems.You will need to define all content <elements /> and the structured content hierarchy.

author: Marco
author_rank: Super Contributor
timestamp: April 29, 2022, 04:53:14 pm
content: I think you can save Excel as a XML type file and manipulate it, with that and the XML transformation language of your choice you can convert it to Docbook ... if you knew a XML transformation language and Docbook in the first place. Docbook is the easier part, don't need to know a lot.

author: Dave
author_rank: Super Contributor
timestamp: April 29, 2022, 05:12:12 pm
content: Latex would be my first pick. Takes a bit of effort to start, but you can get very consistent results when you figure it out.

author: ricko_uk
author_rank: Super Contributor
timestamp: April 29, 2022, 10:41:08 pm
content: I had a look at Latex and didn't find it that quick to learn. Due to being in a hurry and being a little more familiar with XML as well as having so much data already formatted in Excel I will try that first.Thank you all

author: SiliconWizard
author_rank: Super Contributor
timestamp: April 29, 2022, 11:37:10 pm
content: We don't know what kind of format your protocol is currently described with, so it's hard to suggest something that would be faster than manually copy-pasting stuff in the editor of your choice.The benefit of using LaTeX is that you could write some script in your favorite language to extract your protocol from the source it's currently in, and generate documentation automatically from this. If LaTeX sounds intimidating, you could use HTML instead. Pretty straightforward.

author: T3sl4co1l
author_rank: Super Contributor
timestamp: April 30, 2022, 01:21:39 am
content: I feel there's pedant-points available in noting that Excel is already an XML format (.xlsx, compressed container with XML and junk, whatever it is?) so to the extent that's meaningful, it already is.Something a bit more accessible would be a flat text document, well, flat in its presentation -- a single scrolling web page or PDF, say.LaTeX is... it's rewarding to know, and one of the less frustrating open source projects out there -- but it is its own programming language, and -- not that you need to engage with most of those features just to produce a document -- it nonetheless has quite a steep learning curve, and I would definitely not recommend it for a one-off.But it is pretty, I'll give you that.*If your documentation is already descriptive, in the spreadsheet, it might do to simply save that as HTML -- maybe not, uh, saving directly from Excel (which, is that even a thing? -- oh god, yeah, it is?!), but copy-pasting into a suitable HTML editor and saving it as near-verbatim as an HTML table can do, perhaps? Or hell, maybe the Excel output isn't even that useless, dunno. Or likewise for PDF, just printing to that would be fine, again if it's already presentable.Tim*I can't not embed it, again...

author: ricko_uk
author_rank: Super Contributor
timestamp: April 30, 2022, 02:42:55 pm
content: Thank you Tim and SiliconWizzard,I had another look at LaTex but it seems a bit of a steep learning curve for just a one off document. What I am not clear about it what the advantages are of using LaTex in general over Word or - for technical formulas - programs like Mathcad? It seems a lot more difficult to use? Or am I missing something?I am thinking of going the XML route because despite knowing only a little about XML I think I can start becoming much more familiar with it and start using it in embedded software. How, not sure yet, I only read a couple of quick articles on the fact the it is used extensively so I will have to learn more about it... but if you have any pointers or examples on what it could be used for in embedded systems, that would be interesting to know.Thank you

author: T3sl4co1l
author_rank: Super Contributor
timestamp: April 30, 2022, 03:50:39 pm
content: The main thing LaTeX is good for is making slightly nicer documents, particularly for academic purposes. The formatting engine is top notch. It sees a lot of use in academics from computer science (it was created by Don Knuth, after all) to math (the equation formatting is excellent), physics and more.And yeah, hard to use. Like I said, you're not going to go to the trouble for a one-off. No way that's worth it.It's also used in a variety of places for scripted input, like, I recall there's a train line in Germany or Switzerland or something that prints their time sheets this way? Super easy to just plop in the new values, run the tool and there you go, fresh time sheets, looking great as ever. The easiest modern alternative would probably be something like a dynamic webpage, so, you need a database and server, and formatting is limited to whatever the browser can render. So, you can crank away with polishing the CSS, and adding whatever compatibility shims (polyfills) are needed to support whatever older browsers you need to support, and the whole thing takes several seconds to serve to the user, and they must have a browser and internet connection; whereas the PDF output is just, you can share that however you like, pretty much everything has a compliant PDF viewer these days (granted, pretty much everything has a capable browser too). And by then, unless you're already a web design expert, or pay for tools (or a contractor) to set up all this for you -- you're probably in as deep as learning LaTeX for the job in the first place. So, it's maybe not a bad choice in that case.But, there are still simpler ways to generate PDF, that might not look much worse if you're willing to compromise on that a bit.Keep in mind -- what any open source advocate really means, when they encourage something: it's rewarding for its own sake, for the challenge of figuring out and mastering it. Any practical application is merely a convenient byproduct.If you see yourself writing many documents in the future, and want to get output a cut above the rest, I might suggest it -- but definitely don't dive in for a one-off, learn it in your free time (if you have any!). Eventually, get comfortable enough to use it for simple documents (paragraphs, headings, lists, some figures), stick to others for the complicated stuff (multifigures, tables, side bars, weird columns, etc.). In time you'll figure those out too.Point of reference: there are some things LaTeX is justreally bad at. Wrap figures is one example (inline figure with text flowed/wrapped around beside it). They're never placed quite right, you have to specify how tall they are, sometimes they run off the page, other weirdness... Maybe there's a newer package to handle that, I haven't checked in forever, but it's little bothers like that that are par for the course in noncommercial projects like this. Tables... aren't bad, but they're a bit bothersome to set up: lots of commands and alignment symbols needed to build them. HTML tables are a little bit easier to edit I'd say, but they're both very far from just tossing everything in Excel. (There are a few importer tools to convert Excel or HTML tables to LaTeX with not too much editing needed afterwards. But if the mere necessity for such tools makes you wonder -- well, see above, eh?)I honestly don't know much about XML in regards to documentation, though you can use the standard elements as you would with HTML; or, maybe that makes it XHTML, I don't recall. (HTML is a loosely structured ML, whereas X is strict: HTML permits e.g. standalone<p>tags, whose enclosing scope persists until the next block-level tag, or the end of the parent tag. XML requires strict closure, even on singleton tags, hence the shorthand e.g.. XHTML I think is all the standard HTML tags but with strict XML structure enforced?)The main(?) use for XML is as a structured container format: tag names don't matter, as long as they're opened and closed consistently (the structure is valid XML). Such a document won't view as anything in particular in a browser, but it can be parsed into a data structure for ready use in any high level language. They're quite popular for storing configuration data, serialized objects, etc. And yeah, can be nice for embedded, though the structured plain text formatting is rather wasteful, and XML is a bit complex to parse, so you'd avoid using it for the simplest platforms; but like, anything that can run Linux, it's fine.Or, I don't know about serialization; JSON might perhaps be more popular? Probably it depends on the domain, with JSON being more web-centric, because JS, and XML is just wherever. There's lots of domain-specific formats and languages, YMMV.Tim

author: Marco
author_rank: Super Contributor
timestamp: April 30, 2022, 04:05:05 pm
content: Latex is more complicated compared to Docbook and not XML native. XSL mailing list seems to have quite a discussion about Docbook transformations (the Excel XML seems to have somequirks).

author: nctnico
author_rank: Super Contributor
timestamp: April 30, 2022, 04:14:12 pm
content: Just suck it up and format it using MS-Word. Make sure to use consistent styles for headings, text and tables and someone else can do the heavy lifting where it comes to formatting. MS-Word ain't pretty (especially the newer versions that support ODF are very broken where it comes to using text styles) but it is as standard as it can get.

author: ricko_uk
author_rank: Super Contributor
timestamp: April 30, 2022, 04:16:25 pm
content: Thank you all and Tim for the detailed explanation/info.