[WIP] docs ~ INSTALL updates

[rivy]

Consolidate and update various INSTALL documents, including transform into markdown.

[acolomb]

Just a nit-pick, but I believe the standard file name extension for Markdown is .md.

[tleedjarv]

@rivy it seems that the need for commit fd8094c is a bug(?) in Makefile.

INSTALL: $(NAME)$(EXEC_EXT)
# file isn't made for OS X, so check that it's there first
        (if [ -f $(NAME) ]; then ./$(NAME) -doc install > INSTALLATION; fi)

The target name does not match the produced file name.

[rivy]

Just a nit-pick, but I believe the standard file name extension for Markdown is .md.

.mkd is also commonly used, but it's easily changed if desired.

[rivy]

@rivy it seems that the need for commit fd8094c is a bug(?) in Makefile.

INSTALL: $(NAME)$(EXEC_EXT)
# file isn't made for OS X, so check that it's there first
        (if [ -f $(NAME) ]; then ./$(NAME) -doc install > INSTALLATION; fi)

The target name does not match the produced file name.

This was my focus as likely culprit for the problem as well.

It's only failing on the GTK-UI Windows builds with a missing library error. It's using the generated unison binary to generate the documentation file, so, it's likely the same issue with "packaging" (or environment setup) being discussed in #427. Fixing that issue either with early packaging or eval "$(ocaml-env cygwin)", as you noted, would likely fix (at least partially) this problem as well. But, again, as you noted, the recipe target isn't actually created by the recipe as written. So, that makefile target/recipe likely needs a pass by someone who is MacOS-centric and understands what and why it's creating the INSTALLATION file and whether it should be INSTALL, instead. It may be that the recipe target can be simply changed to INSTALL.mkd if that's a reasonable substitute for INSTALL or INSTALLATION.

I can put some text into INSTALL (eg, "Refer to INSTALL.mkd") for now to patch over the problem for the moment.

[tleedjarv]

The comment about macOS refers to $(NAME) (that being unison), which means that UISTYLE=mac does not produce unison executable (it produces Unison.app). So that comment is not relevant in this case.

In my view, this make target can just be removed for good by this PR because all the information is already in the files created/modified by this PR. If something's missing then it could be added. Execute unison -doc install and see for yourself. I suspect that this kind of "generation" was originally added due to the original content being written in TeX.

[rivy]

@tleedjarv , thanks for the clarification. That makes much more sense to me now.

If no one objects, I'll add a commit removing that recipe (with an explanation).

[tleedjarv]

Should INSTALL* files be moved up one dir, from src to repository root? Perhaps not in scope of this PR, but the same question for file CONTRIB, COPYING (which already exists with name LICENSE), NEWS, README (also already exists with name README.md).

[gdt]

I tend to think agree with moving; it is normal for a user to look at top-level and that's where the GNU coding standards as enforced by automake say things go (not that we have adopted that formally, but it's the closest thing there is to a standard approach).

How about lets rename INSTALL to INSTALL.md in place and spiff up content, and have a separate change that does reorganization with no content changes.

[bcpierce00]

Go for it. The reason things live in /src now is that, back in the day, we liked to distribute “just the OCaml sources” as a single tarball that was easy to compile and didn’t include any latex or other stuff. We’ve stepped away from that distribution model in favor of GitHub.

[rivy]

I tend to think agree with moving; it is normal for a user to look at top-level and that's where the GNU coding standards as enforced by automake say things go (not that we have adopted that formally, but it's the closest thing there is to a standard approach).

How about lets rename INSTALL to INSTALL.md in place and spiff up content, and have a separate change that does reorganization with no content changes.

It's easy enough for me to move the files to the main directory as a single initial commit and then rebase the changes on top. I'll proceed in that manner if there's no objection.

It seems that *.md might be the preferred naming scheme. So, I'll use that as well, again, sans objections.

[gdt]

A good point that your strategy is more than good enough and gets more done, so ok with me.

[rivy]

I moved the INSTALL-type files into the main directory as an initial commit. It seemed most reasonable to move the rest of the development/developer documents into the main directory as well (done in the second commit which can be easily dropped if move is not desired). Someone with a more top-level view will need to look at the src/README file to see what, if any, of it should be merged into the main directory README.md.

INSTALL.win32-cygwin-gnuc.md is fully fleshed out but is still in need of some editing.

I'll proceed with further revision of INSTALL.md and INSTALL.win32-cygwin-MSVC.md in the near future.

Comment/critique/discussion is welcomed.

[tleedjarv]

It looks to me like README and README.md should be merged.
COPYING and LICENSE are now duplicates. I don't have a recommendation which one should be kept.

[gdt]

I lean to COPYING as more what people are used to, but there is no right and wrong here.

[rivy]

It looks to me like README and README.md should be merged.

Agreed, but what of src/README should be kept and/or changed?

More specifically,

• What is the main repository/home page (here [https://github.com/bcpierce00/unison] or http://www.cis.upenn.edu/~bcpierce/unison)?
• Where should bug reports go?
• Is unison-users@groups.yahoo.com still the preferred point for discussion and questions (is it even functional?)?

[bcpierce00]

What is the main repository/home page (here [https://github.com/bcpierce00/unison <https://github.com/bcpierce00/unison>] or http://www.cis.upenn.edu/~bcpierce/unison <http://www.cis.upenn.edu/~bcpierce/unison>)?

Seems like we might as well consider GitHub the main home page now?

Where should bug reports go?

Github.

Is ***@***.*** still the preferred point for discussion and questions (is it even functional?)?

Yes, I think it’s still functional and a fine place for questions?

[gdt]

My take is:

• github is the homepage (I don't really like this, but it is how it is)
• bug reports belong on github issues. I don't think we have another functional place
• yahoo anything is, in late 2020, broken, on thin ice and going to be deleted in about a month. We have moved away from it and the mailinglists should be described as being unison-users@seas.upenn.edu and unison-hackers@lists.seas.upenn.edu.

[bcpierce00]

The homepage can continue being the old site at UPenn — that’s no problem

…

On Nov 22, 2020, at 8:37 PM, Greg Troxel ***@***.***> wrote: My take is: github is the homepage (I don't really like this, but it is how it is) bug reports belong on github issues. I don't think we have another functional place yahoo anything is, in late 2020, broken, on thin ice and going to be deleted in about a month. We have moved away from it and the mailinglists should be described as being ***@***.*** ***@***.***> and ***@***.*** ***@***.***>. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#429 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABVQQC3RQOXZM37L7PIQ3PLSRG4E5ANCNFSM4TQG5BKA>.