Increase the maintainability of (installation) documentation

[chrisdembia]

It's come up in other issues that if the (install) documentation were in a plain text format, it would be easier to maintain. See #47, #48.

Do we want to move the install documentation? An option would be to write them in Markdown/RST, which could be converted into a PDF using pandoc or something like that.

[sherm1]

Great idea. Probably no need ever to convert it to pdf in that case. Many projects just put the install docs in the README.md file at project root, in which case it shows up right on the github page. Simbody's README.md is seriously underutilized!

[chrisdembia]

Get off the computer!!

[chrisdembia]

If we move the instructions to the README, then I don't think we can keep the images. An alternative is to write an HTML page.

[scpeters]

On the contrary, you can include images in markdown (copied from markdown cheatsheet):

![alt text](https://github.com/adam-p/markdown-here/raw/master/src/common/images/icon48.png "Logo Title Text 1")

[chrisdembia]

Oh neat. Can you view the markdown file in a way that'll show the image,
without converting it to html first?

On Sat, Oct 19, 2013 at 1:01 PM, Steven Peters notifications@github.comwrote:

On the contrary, you can include images in markdown (copied from markdown
cheatsheethttps://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#wiki-images
):

[image: alt text]https://github.com/adam-p/markdown-here/raw/master/src/common/images/icon48.png

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/50#issuecomment-26657687
.

[scpeters]

On my mac, I can view markdown files with quick-look using code from here.

There's also a basic web form.

ipython notebooks can do markdown too.

I suspect you could find other editors as well.

[chrisdembia]

I like Markdown. But if it's not common for Windows users to have a way to view Markdown with images, then I'm not sure we should use Markdown. I think the current instructions are written for an audience that wouldn't want to hunt for their own way to view Markdown.

Maybe there are two versions of the installation instructions: Simple Markdown instructions in the README.md (which is displayed on GitHub), and a more lengthy document for more detailed instructions. For the latter, I think it would make sense to put this in the doxygen. Then the README.md can give a link to the doxygen hosted somewhere online.

[chrisdembia]

Wow cool! Doxygen supports the following (see this project's Doxyfile.in):

# If the USE_MD_FILE_AS_MAINPAGE tag refers to the name of a markdown file that
# is part of the input, its contents will be placed on the main page (index.html).
# This can be useful if you have a project on for instance GitHub and want reuse
# the introduction page also for the doxygen output.

USE_MDFILE_AS_MAINPAGE =

[sherm1]

I think my attempt at a build-for-dummies document (with CMake GUI screenshots, etc.) was ill-conceived because I didn't think about the maintenance difficulty for a very small team with lots of other things to do. For practical reasons it would be preferable to have a less elaborate but easier to maintain document, maybe swapping the images for some text in which case markdown might be a good option. And having the instructions exist in only one place is a good way to avoid trouble. An alternative might be to supplement README.md with some github Wiki pages that are more easily kept up to date than Word documents buried in the repo.

[chrisdembia]

I definitely appreciate that such material exists; I remember having to scrounge the internet to learn such things. For "dummies," we can make general info pages that do not depend at all on the state of Simbody ("this is how CMake looks and works."), or forward people to such resources online, if they exist.

[chrisdembia]

Okay so Doxygen can pick up Markdown files, and should be able to include images. I tried converting the current Windows build .DOC to Markdown, and it was fairly easy to do (using pandoc). There are already brief instructions in doc/INSTALL.txt. We could move those to README.md, and convert the .DOC's to Markdown, and include the build instructions Markdown in the Doxygen. Of course, the lengthy build instructions need to be revised after they're converted to Markdown.

This way, a user who has just obtained the source code has full access to all the build documentation, though only in Markdown (which is good for developers, because it's more maintainable). If they want to get the full build documentation in HTML BEFORE building it themselves, they can go to the Doxygen hosted online.

The only disadvantages are if (1) users would prefer PDF build instructions over html build instructions, or (2) users don't want to have to go online to get the html build instructions (before building on their own).

Then we can also consider doing this for the users guide??

[sherm1]

The user's guides and other docs could use some work, but I think only the installation is critical because it can be used to bootstrap the rest, e.g. explain how to get everything else including docs in whatever format.

[chrisdembia]

Now that the README has mostly accurate install documentation, what should we do with the previous installation instructions?

[sherm1]

I would like to say we simply delete them and depend on the README.md, which should be easy to keep up to date. Do you think that's reasonable?

[chrisdembia]

Yeah; I think we should have only one location with build and installation instructions. However, there's probably some good stuff in those documents that I neglected to put in the README.md. I could make a pass through those documents, and carry over anything I think would be good to keep?

[sherm1]

Sounds good!

[sherm1]

I'm going to close this now since I think you have drastically improved the situation. We can file separate issues for more specific problems we find.

[chrisdembia]

I imagined that we would close this issue after deleting the old install documentation.

[sherm1]

I would rather replace it with specific tasks now, if only to acknowledge the work you've already done!

[sherm1]

I filed #172 on the bad installation instructions in the User Guide.

[ghost]

I was setting up my environment and doc/INSTALL.txt confused me a lot. I am willing to help out with the documentation but I am just starting to get myself familiar with Git and simbody both.

[chrisdembia]

Use the README.md. The doc/INSTALL.txt is out of date. File a new issue if the README.md is also lacking.

[ghost]

Thanks, Chris. I used the README.md and everything seems to be working well. Instructions in README.md were very clear. I am not 100% sure but the following line in README.md may need to be revised.

$ sudo echo 'export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:~/simbody/lib' > /etc/profile

First I had to give write access to /etc/profile and I ran the below command:

$ sudo echo 'export DYLD_LIBRARY_PATH=:~/simbody/lib' > /etc/profile

[chrisdembia]

Would that discard any setting you previously had for DYLD_LIBRARY_PATH? Does := append? EDIT: I see that := is expansion assignment, which seems irrelevant here, and =: just uses an empty path as the first path.

This is the issue you ran into: http://superuser.com/questions/54814/sudo-unable-to-write-to-etc-profile.
http://serverfault.com/questions/68541/bash-how-can-i-add-a-line-to-the-end-of-a-file-which-i-only-have-access-to-via/68557#68557

This points out another issue with that README: the >'s should be >>'s, for appending.

I'll update the README in a second.

[ghost]

Semicolon itself appeared in the path that is assigned to DYLD_LIBRARY_PATH; therefore, I instead ran

$ sudo echo 'export DYLD_LIBRARY_PATH=~/simbody/lib' >> /etc/profile

Above command adds the env variable at the end of /etc/profile. I mistyped the command I ran in my previous comment. Please ignore that.

[chrisdembia]

Okay. Let us know if you run into any other build/install problems.