search

IreneKnapp / modern-data

A self-describing binary data format for dependently-typed object graphs.
MIT License
13 stars 0 forks source link

documentation project #1

Closed tinyplasticgreyknight closed 9 years ago

tinyplasticgreyknight commented 9 years ago

I've started a documentation project here: https://github.com/tinyplasticgreyknight/modern-docs

It can generate most of the same documentation as the original in ReST or any format supported by Sphinx, e.g. HTML, PDF, epub, texinfo, even manpages!

I think you mentioned (somewhere) that Modern Data kind of includes more than just data, and you weren't sure if maybe it should be just called "Modern", or something like that. I haven't taken any real actions on this so far though, apart from the title.

I still need to fill in the lists of C library functions, then I can start digging for more detail on the places where I'm not quite sure what the function of some item is (e.g. how are integers marshalled by cast_int64_blob, and so on). Other tasks are listed on the issue tracker

It gives some nice auto-formatted type signatures for the builtins, and it even parses modern.h to make sure it has the right type signatures for the C library functions!

I feel good about this (and I understand Modern better now too!). :-)

IreneKnapp commented 9 years ago

Oh, wow, you've been busy! This is a good move, thank you. It's likely that there's sufficiently little manually-generated content in the original that migrating anything that got missed by hand will be more than sufficient.

I'm going to see tonight if I can get you the table of contents of the original docs, since it serves as a list of things that should be written at some point. I'll open an issue over on your repo if I am. :)

Parsing modern.h is quite impressive, by the way. I like that approach a lot.

IreneKnapp commented 9 years ago

Oh - regarding the name - I think what you're thinking of is a data type name issue, not the name of the overall project. I feel like "Modern" is a bit of a generic term that would be difficult to Google for, so for the project I want to keep it "Modern Data" unless someone has a much better idea.

If you look at https://github.com/IreneKnapp/modern-data/blob/master/C/library/modern.h#L6 it's typedef void modern;, whereas it used to be modern_node; it essentially got too irritating putting that longer name everywhere, and this is the most-used type for client code, so giving it the shortest name hopefully communicates that.