proper documentation on markdown encoding

[arademaker]

Do you have any documentation about the proper use of markdown to preserve the law structure?

[hhirsch]

Markdown is well documented and capable of structuring a document "close enough" or "well enough" for the use case. Go ahead and outline what particular feature is missing though. The project appears to be abandoned. I'd take over maintneance but I don't think there is a lot of public interest and the scope is too broad, wanting to be both a platform to display all the laws and at the same time wanting to be a platform to draft new laws.

[AliSajid]

I actually wonder if this can become part of something general. Effectively a machine-readable and machine-searchable law drafting platform with this being an implementation. A text-based database that is static sounds like a great idea.

[hhirsch]

@AliSajid Sadly it is unmaintained.

[arademaker]

We are trying to do something similar with Brazilian Laws. I am playing with org-mode and Markdown. At first, org-mode has the benefits to allow metadata in all headers (tags and properties). Markdown, on the other hand, is well supported and don't force anyone to use a particular editor. I wonder if this project had already some 'lessons learned' about how to handle the main document divisions (article,s chapters, titles etc), references to other laws, revisions, metadata etc.

Our take so far: https://github.com/own-pt/oab-exams/tree/master/lexml the original document posted in the official Brazilian Senate (http://www.planalto.gov.br/ccivil_03/Leis/L8906.htm).

[stefanw]

Hi everyone, thanks for the interest.

I did not create a standard for law in Markdown, I shoehorned the existing HTML version of German laws into Markdown. I wanted the law to be easily readable and writable by both humans (e.g. through PRs) and machines, that's why I chose Markdown. Obviously, Markdown was never meant for laws, it's only an easier to read/write subset of HTML.

Here are some lessons learned concerning the use of Markdown for annotating laws:

• I kept metadata in the YAML front matter. That worked reasonably well, but you have to know what your markdown file represents (e.g. a law, a section, a law book?). Some laws in Germany are really long (e.g. BGB), but most are short. The version and change meta data was kept in Git which did not work too well, mostly due to the poor technical process of how our laws come together.
• In most cases the encoding was straight forward: headings, paragraphs, ordered lists and sublists.
• But Markdown is limited HTML and you likely need extensions to represent all of your law's structure, e.g. footnotes and tables. Laws may also contain images.
• HTML only supports six levels of headings – some German laws had more and there's no way to fix this with an extension.
• The 'machine readable' idea of this project is obviously only meant as 'machine formatable'. This works mostly, but e.g. if you want to link the references in a law to another law in Germany, you need more than just a RegEx, there are many different ways and it can get quite complicated. Ideally you keep some metadata on references in Markdown which I had not done in this project.

If laws were written with the restrictions of a Markdown dialect from the start, it could work. But realities are more complex and this leads to the current standard for storing laws: Akoma Ntoso. I can understand how it comes to complex standards, but I still believe there's hope for the idea that the law – even though it can be complex in its semantics – doesn't need to be complex in its (storage) format. After all what gives the law its power are not the XML-tags around it, but the people who read, write and change it.

This was the rough road map for this project:

1. Find a good format to represent the law
2. Find a good way to store changes with author and possibly procedural metadata in version control
3. Keep it up to date with commits as changes to laws
4. Build tools around the project and make professionals use it in their work
5. Get it adopted by your parliament ;)

BundesGit had some promising prototypes for 4, but basically failed in step 3. I couldn't automate the semantic changes as separate commits.

So even though this project is unmaintained, I believe the idea of plaintext laws in version control lives on.

[hhirsch]

@arademaker If you want feature complete typesetting for law while having a free and open stack I'd opt for latex. As much as I love it, you'll never get non-emacs-users to use org-mode.