0

There's this file format which I want to write some documentation for. It's intended for humans, but should be specific enough so that a person could essentially parse the format (if perhaps slowly) by himself, using this documentation. What I have is:

  1. Myself (i.e. this doesn't need to be automated, I need assistance creating/writing the documentation)
  2. Some code which currently parses the file whose format I'm documenting

I want something which will make it easier for me to express what-comes-after-what, what-can-fit-in-what-field etc., so that I end up with a semi-graphical layout of what's in the file, or something like a markup which is relatively easy to read etc. I realize this sounds a bit vague, but I can't be quite exactly what I need until I actually start using it.

Requirements:

  • Gratis
  • Allows saving/exporting in well-known and further-convertible format.

Desired:

  • Libre

Notes:

  • In my specific case the format is not binary, its text-based, but if you have a more general answer you're welcome. Here's a (slightly obfuscated) snippet:

    FOO.bar, BAZversion 1234
    8 8 16
    FOOsize=1063
    3 64 system_auth_user 3 0 1 256 0 str 1 1 1409 0 0 0 0 0 1 256 0 8208 10240 0
    4 64 system_auth_passwd_v2 4 0 1 256 0 str 1 1 1409 0 0 0 0 0 1 256 0 8332 10240 0
    48 32 snapshots_bid 60 0 0 256 0 int 4 0 1409 0 0 0 0 0 0 1024 0
    
  • It can be web-based, I don't care.

  • It can be a combination of software tools or a piece of software + method of using it
  • Are we talking about a byte byte layout? or at least "section A begins at offest X, and the first two bytes are its length. Section B follows the end of section A ...." Could you give a small example? I am interested in this question – Mawg Dec 21 '17 at 9:04
  • 1
    @Mawg: No, not a byte-by-byte layout since it's a textual format. I'll link to a small example. – einpoklum Dec 21 '17 at 10:39
  • Can you code? Would you be willing to code a parser for others to use? If so, you can't really beat Antlr, especially if you use the visual ANTLR workbench and plugins for Eclipse, NetBeans, etc – Mawg Dec 21 '17 at 11:13
  • 1
    @Mawg: There already is a parser in existence. But there's no documentation for people who want to understand the format in context of other aspects of the software system using it. I want to write that documentation. Would Antlr really help me with that? – einpoklum Dec 21 '17 at 13:17
  • 1
    Boost Spirit X3 is not about regexps - it's a powerful parser which, after compilation, should be very fast. It also makes it so that the formal specification of the grammar to be parsed is done in a way that's both relatively intuitive and at the same time valid C++ code. See this. But we're going off-topic here. Oh, and about Lemon: Wikipedia article. – einpoklum Dec 23 '17 at 13:27

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Browse other questions tagged or ask your own question.