Skip to content

Commit

Permalink
Review and update Install doc (#331)
Browse files Browse the repository at this point in the history
* Review and update Install doc

Formatted overview on ways to install to a table.
For me this works better to compare variations.
It also helped me to fill in some missing blanks.
And to remove some details unnecessary for an overview (I moved some of
these details down to specific install sections).
Let me know if this works for you too.

Noticed that overview mentions how to switch versions but install
instructions do not talk about this. Did nothing about this yet.

Subtle: tried to use "we" only when talking from Polylith core team, and
used "you" when talking to and guiding the reader.

Assumed poly core team preference is poly as stand-alone and/or Clojure CLI dep.
Can adjust advice if this is not the case.
But making some clear suggestion avoids overwhelming newcomers.

Noticed some prerequisite and post-install advice repeated in some
install instructions. But inconsistently. I moved these to adoc custom
attributes so we have less copy/paste.

Now using adoc `subs="attributes+"` option in code blocks.
This way code blocks can now reflect the `:poly-version:` attribute.

Moved clojure cli dep install instructions before clojure tools
install instructions. This matches the overview order, and it (maybe?)
the more likely order of interest for readers.

Added "stand-alone" to all headings that describe stand-alone
installation. Just to make it extra clear.

Moved logging deps config to tools deps usage section as it only
applies to that usage.

Re-orged Clojure Tools instructions a bit.
Clarified, I think, how it processes args.

Noticed that JVM options only applies to stand-alone variants to added
that detail. I also noticed that it does not give an example, which I
thought would be useful, but did nothing about that.

* review feedback: header style for 1st table col

And append colon to 1st col text.

* review feedback: Running from master

Also got around normal heading capitalization convention by quoting
master as code.

* review feedback: text as lang for poly shell block

* Restore link to poly release strategy
  • Loading branch information
lread authored Sep 16, 2023
1 parent 81cc12f commit 138c86b
Showing 1 changed file with 192 additions and 130 deletions.
Loading

0 comments on commit 138c86b

Please sign in to comment.