Consolidate specification docs into a master specification doc

[milancurcic]

Somewhat related to #4.

Currently we have individual specification markdown documents for each module and we place them in the src/ directory.

Personally, I find that it'd be much easier to read the spec if we consolidated all the spec docs into a a single markdown file. Then we could have heading 2 for each module and heading 3 for each procedure. More importantly, if you wanted to show stdlib to somebody and have them see what's currently implemented, you could point them to a single document where they could see everything.

Second, spec docs shouldn't be in src/--this directory is for source files. Specification would be more accessible in the top-level directory. (I personally only read the spec docs on GitHub where they're rendered nicely).

I'd be happy to take a stab at this if the community agrees it's a step forward.

@certik @jvdp1 @ivan-pi What do you think?

[jvdp1]

I agree with both points: all specs could be merged into one single document, and they should not be in src (intuitively I will not check src to find some docs).
It was convenient to keep it as now as a starting point. I guess it will also depend how #4 will be implemented.

[ivan-pi]

I agree the current set up is not optimal. Also the src/ directory is starting to get crowded.

I don't think having one single markdown file is a good idea on the long term, it will quickly become too big, and people might mistakenly edit the wrong section, or delete something by accident, etc.. Maybe having separate markdown files for each module and merging them using pandoc upon pull requests would be a way to go (sort of like suggested here?

I'm torn between including the documentation directly in the source files or our current approach. On one hand, including the documentation in the source files halves the number of files necessary to maintain and the documentation can be easily edited along with the code. On the other hand, it is easier to write markdown in a separate file (without having to write comment symbols, and using editor snippets), also the source code is more streamlined.

[jvdp1]

I'm torn between including the documentation directly in the source files or our current approach.

Shouldn't it be based on how the documentation #4 is developed?

[certik]

I don't feel strongly either way. The goal is to have an implementation independent specification so that one can implement a different implementation (perhaps commercial and/or faster) using it --- and this might later go into the Standard itself. If there is a better way to organize this specification, then let's do it.

[ivan-pi]

I'm torn between including the documentation directly in the source files or our current approach.

Shouldn't it be based on how the documentation #4 is developed?

Yes. Perhaps my comment would be more suitable in that issue.

The goal is to have an implementation independent specification so that one can implement a different implementation (perhaps commercial and/or faster) using it --- and this might later go into the Standard itself.

If this is part of our plan, I think we should have an independent specification document. It would be annoying to have to look for the specs in the code source itself (or on some auto-generated website).

[zbeekman]

This issue might be closeable thanks to #183. It's at least a step in the right direction.

Also, now the specs can use the FORD linking syntax to link directly to the API documentation.

[jvdp1]

Also, now the specs can use the FORD linking syntax to link directly to the API documentation.

This linking syntax sounds what I was looking for. How should I use it? It is not clear from the doc. Could you point to an example, please?

[zbeekman]

This linking syntax sounds what I was looking for. How should I use it? It is not clear from the doc. Could you point to an example, please?

For future reference, I added some and a comment with explanation in PR #198.