Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[WIP] docs ~ INSTALL updates #429

Draft
wants to merge 8 commits into
base: master
Choose a base branch
from

Conversation

rivy
Copy link
Contributor

@rivy rivy commented Nov 10, 2020

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

@acolomb
Copy link

acolomb commented Nov 10, 2020

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

@tleedjarv
Copy link
Contributor

@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
Copy link
Contributor Author

rivy commented Nov 10, 2020

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
Copy link
Contributor Author

rivy commented Nov 10, 2020

@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
Copy link
Contributor

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 rivy mentioned this pull request Nov 10, 2020
@rivy
Copy link
Contributor Author

rivy commented Nov 11, 2020

@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).

@rivy rivy force-pushed the docs.install-update branch 3 times, most recently from 2a1c3b1 to 94f3d9c Compare November 15, 2020 21:00
@tleedjarv
Copy link
Contributor

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
Copy link
Collaborator

gdt commented Nov 16, 2020

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
Copy link
Owner

bcpierce00 commented Nov 16, 2020 via email

@rivy
Copy link
Contributor Author

rivy commented Nov 16, 2020

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
Copy link
Collaborator

gdt commented Nov 16, 2020

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

@rivy
Copy link
Contributor Author

rivy commented Nov 18, 2020

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
Copy link
Contributor

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
Copy link
Collaborator

gdt commented Nov 20, 2020

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

@rivy
Copy link
Contributor Author

rivy commented Nov 22, 2020

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,

@bcpierce00
Copy link
Owner

bcpierce00 commented Nov 22, 2020 via email

@gdt
Copy link
Collaborator

gdt commented Nov 23, 2020

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
Copy link
Owner

bcpierce00 commented Nov 23, 2020 via email

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
DRAFT PR is not ready to merge
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants