Add base README.

org_rw/README.org

@@ -0,0 +1,34 @@
+* Org-rw
+
+A python library to parse, modify and save Org-mode files.
+
+* Goals
+- Reading org-mode files, with all the relevant information (format, dates, lists, links, metadata, ...).
+- Modify these data and write it back to disk.
+- Keep the original structure intact (indentation, spaces, format, ...).
+
+** Safety mechanism
+As this library is still in early development. Running it over files might
+produce unexpected changes on them. For this reason it's heavily recommended to
+have backup copies before using it on important files.
+
+By default the library checks that the re-serialization of the loaded files will
+not produce any change, and throw an error in case it does. But this cannot
+guarantee that later changes to the document will not corrupt the output so be
+careful.
+
+Also, see [[id:76e77f7f-c9e0-4c83-ad2f-39a5a8894a83][Known issues:Structure modifications]] for cases when the structure is
+not properly stored and can trigger this safety mechanism on a false-positive.
+
+* Known issues
+** Structure modifications
+:PROPERTIES:
+:ID:       76e77f7f-c9e0-4c83-ad2f-39a5a8894a83
+:END:
+- The exact format is not retained when saving dates/times. This might cause problems with the safety mechanism if you have dates that.
+  Note that in both cases, doing ~C-c C-c~ on the date (from Emacs) will change it to the format that Org-rw serializes it to.
+  - Use multiple dashes for hour ranges, like =<2020-12-01 10:00----11:00>=. It will get re-serialized as =<2020-12-01 10:00-11:00>=, thus triggering the safety mechanism as unexpected changes have happened.
+  - Same in case hours are not two digits (with leading 0's if needed), like =<2020-12-01 9:00>=. It will get serialized as =<2020-12-01 9:00>=.
+
+* Other python libraries for org-mode
+- [[https://github.com/karlicoss/orgparse][orgparse]] :: More mature, but does not provide format support or writing back to disk.