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
9
  • 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 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 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.