Show HN: Braq – The most obvious way to section a document

Hi HN ! Alex here, and I&#x27;m thrilled to show you Braq (<a href="https:&#x2F;&#x2F;github.com&#x2F;pyrustic&#x2F;braq">https:&#x2F;&#x2F;github.com&#x2F;pyrustic&#x2F;braq</a>), my most obvious way to section a document.<p>Braq is one of two spin-offs of Jesth (<a href="https:&#x2F;&#x2F;news.ycombinator.com&#x2F;item?id=35991018">https:&#x2F;&#x2F;news.ycombinator.com&#x2F;item?id=35991018</a>) which is an unorthodox data format for which I struggled to design a library with a very simple programming interface.<p>Jesth was supposed to divide a text document into sections, each consisting of a header and a body. A subformat was available to formally represent structured data in a section. This subformat was optional, allowing for an eclectic set of sections within the same document.<p>I extracted and improved the subformat in a new spin-off project named Paradict (<a href="https:&#x2F;&#x2F;news.ycombinator.com&#x2F;item?id=38684724">https:&#x2F;&#x2F;news.ycombinator.com&#x2F;item?id=38684724</a>).<p>Braq is the other spin-off project that focuses on Jesth&#x27;s main idea: just section a document and let the programmer decide what to do with each section. So a section can be a JSON string, a prompt for a chatbot, ASCII art, a note, etc.<p>On top of the Braq data format, we could build something else, such as a docstring format which will be consumed by a documentation generator.<p>This is an example of a Python function with its docstring written in a format designed on top of Braq:<p><pre><code> def sum(a, b): &quot;&quot;&quot; This function returns the sum of two integers [params] - a: integer - b: integer [return] Sum of a and b [errors] - OverflowError: raised when either a or b is too big - IntegerError: raised when a and b aren&#x27;t integers &quot;&quot;&quot; pass </code></pre> Note that the above docstring format exists and the documentation generator that consumes it is not public. This docstring format is visible in the source code of my projects (<a href="https:&#x2F;&#x2F;pyrustic.github.io" rel="nofollow">https:&#x2F;&#x2F;pyrustic.github.io</a>).<p>Braq is also used by Paradict for config files. This is what a config file in Paradict format might look like:<p><pre><code> [user] # no comment id = 42 name = &#x27;alex&#x27; birthday = 2042-12-25T16:20:59Z books = (dict) romance = (list) &#x27;Happy Place&#x27; &#x27;Romantic Comedy&#x27; sci_fi = (list) &#x27;Dune&#x27; &#x27;Neuromancer&#x27; </code></pre> Braq is available on PyPI and you can learn more by reading its README or browsing the source code.<p>Let me know what you think about all this !