BSV User Guide, Reference Manual etc. not available

[flokli]

Since the bluespec.com relaunch, links from http://wiki.bluespec.com/Home/BSV-Documentation linking to various downloads at http://www.bluespec.com/forum/download.php?id=xxx locations are not reachable anymore.

I'd be very helpful if those could be recovered, to help newcomers and users that want to use Bluespec.

Depending on how the docs are generated, those could probably be hosted through GitHub pages, readthedocs.io, or be part of a GitHub Wiki.

[rsnikhil]

The Reference Guides for both BSV and BH are currently available at https://github.com/BSVLang/Main. That repo was created some years ago fro BSV/BH language-related info, including ref guides, tutorials, etc. Now that bsc has been open-sourced I will be updating and moving all that material here to this site, as a sibling repo to the bsc repo. Hopefully within the next month or so.

[thoughtpolice]

I think it would be nice to actually keep things in the bsc repository. Notably, it makes it much easier to synchronize things like release branches with various versions of the manual, documentation, etc, which I imagine will be developed in tandem for quite a while, at least. It also makes it easier to ensure that various things like documentation updates properly happen when patches are written to the compiler, because otherwise it's very difficult to catch up with things you missed.

My experience with GHC was that keeping documentation close to the code is very important! Separate repos creates friction. It's useful for some things, but not all -- for example, a book/tutorial in the style of The Rust Book or Theorem Proving in Lean are better suited as separate code repositories: they're long form, detailed, have custom styling and possibly build requirements (e.g. to ensure that all code samples are semantically/syntactically correct), and more. They conceptually are their own project.

However, things like a manual for the compiler, and documentation about the standard library, etc, are much, much better suited to go directly into this repository I believe. That is because things like the Prelude will be developed directly in tandem with the compiler.

The language reference is somewhat tricky, because conceptually it's independent of the compiler, but practically I imagine they're fairly closely tied anyway. However, the bsv-reference-guide is, at the moment, kind of all of those things. It's a manual for the compiler (e.g. describes how (* synthesize *) works), a semantic language reference (the static/dynamic semantics), and a reference for the standard library (e.g. all the types, their uses, etc). Ideally, these should be separate, I feel.

For instance, I would expect information about how to guide synthesize annotations, how to use bluetcl, compiler flags, and integration with 3rd party vendor synthesis tools (i.e. "What to know when using Vivado" or whatever) to be in the compiler manual, and library documentation to be in another sibling manual. The actual language semantics (which I think are best described in terms of formal static/dynamic semantics) I think could, and perhaps should, be in a separate repository with their own pacing and structure.

Previously I worked on adding a manual for Clash to https://clash-lang.readthedocs.io, which is automatically generated by the source code inside the clash-compiler, under the docs directory: https://github.com/clash-lang/clash-compiler/tree/master/docs -- would y'all be open to something like this? For example, we could have https://bluespec.readthedocs.io and the documentation could be entirely generated from a docs subdirectory. This can be setup very easily. We can then begin the process of writing the manual just by making ordinary pull requests to it.

So I think really, it would be gradual splitting/re-writing of the manual into a new format. The organizational structure might look something like:

• b-lang-org/spec -- language specification, including syntactic forms, and dynamic/static semantics. It would be expected that this is mostly of interest to PLT nerds.
• b-lang-org/bsc: This repository, but containing the raw compiler reference manual, and the documentation for the built-in libraries. Built by the CI in this repo, too.
• b-lang-org/book -- full-blown (future) book to learning Bluespec, from start to finish. Totally independent of the previous projects, and a full project in its own right.

@rsnikhil Would y'all be open to something like this? It's quite easy to get readthedocs running, and I'd be happy to flesh out an example of what it might look like when deployed, etc. I think this approach is more work but ultimately a pretty nice split of the documentation into the proper places. Splitting up the reference manual will take time but I think is the right way to go, perhaps.

[quark17]

I was recently looking at the LaTeX source for the compiler User Guide. (If you recall, aside from the book and tutorials, there are two main guides/manuals that currently exist: the BSV Language Manual and the BSC User Guide.) The latest version of the user guide had been updated to combine documentation for BSC with documentation for the development GUI. When BSC was put on GitHub, the GUI wasn't included. I recently created a new repo on GitHub for that GUI in open source form (see bdw ) and as part of that, I extracted GUI documentation out of the User Guide and made it into its own document, and put the source in a doc directory in that repo.

I now think that I can easily put the rest of the User Guide LaTeX source into a document for BSC, to go into this repo. And I'm planning to do that in the coming weeks.

I will also follow @thoughtpolice 's suggestion of extracting the library documentation from the BSV Language Manual and making it into its own standalone document -- also to go in this repo.

There is still the rest of the BSV Language Manual to put somewhere -- and whether to remove any other parts of it and put them into BSC-specific documentation. And the library documentation will be in BSV, and it may be worth figuring out how to create a BH/Classic variant of the document. But those are things we can work on once this first bit is put into the repo. So look for that soon!

[quark17]

I've submitted PR #301, adding source LaTeX for the BSC User Guide and the BSC Libraries Reference Guide. Both documents could use a lot work. I also took a stab at including it in the CI, which also could maybe be done better.

The README's "docs" button still goes nowhere, and should be updated to point to something. I am not familiar with ReadTheDocs, but I can look into that. Although we might want to have a docs "overview" page, that lists all the available resource. For example, @rishubn pointed out that folks at MIT wrote some intro guides [here].

[quark17]

The BSV and BH language manuals have been added to this repo, so I think that all of the documents in the original request are now available. Providing HTML and/or accessible versions (at a site like ReadTheDocs) is the subject of issue #377, and that discussion can continue there. I think we can close this issue, then.

Before closing, though, I do want to fix up the README. An earlier comment mentioned that the "Documentation" tab didn't go anywhere -- that's been fixed, by having a "Documentation" section further down. That section needs to be updated to mention that the language manuals are now available. PDFs are available in this repo if you go the Releases page and click on a specific release (where the PDFs in that release are attached). Where the "Documentation" section mentions the various the documents, it doesn't have any direct links to those PDFs, but further down it mentions (and links) to the Releases page. Unfortunately, people don't read closely (or far enough) and don't see that they can follow that link; it would be good to have links at each mention of the documents. The problem is that there is no "latest" link that we can use to link to PDFs in whatever the latest release is. Instead, we have to link to a specific release tag, which means that we'll need to remember to update those links in the README every time a new release is added. (ReadTheDocs supports a link for "latest", so we won't have this process if we eventually start hosting the docs there.) I would also like to add links to third-party documention in that section of the README -- such as the MIT intro guide linked in a earlier comment here.