Review all README/documentation to remove outdated/duplicate content

[jmdh]

This file is severely out of date, but still probably contains useful snippets. It should probably be reviewed and merged with the top-level README.

[Tux]

I updated most of the serious historic flaws. Karl is testing the current docs to the letter in doing exactly what it states and changing the docs along the way. Once done (I sit next to Karl to verify or comment on every change) I'll ask Jim to convert the README to MarkDown and improve on style and consistency

[jmdh]

for the avoidance of doubt, U/README.dist hasn't been touched since 2011 (aside from the small change to fix a specific error from me earlier). There's also U/README which again needs an overhaul/removal. I'll retitle this ticket accordingly. (+ @jkeenan as you were mentioned above)

[khwilliamson]

I have issued PR13 for fixing this up.

One thing I mostly didn't change is the instructions for (k) Porting/mksample. I ran this and immediately regretted it because the changes were so vast from what came before. I think Tux should figure this out.

Also, in step (a). This is so confusing to me that i don't know how to clarifiy it.

[jkeenan]

On 10/18/2017 04:07 PM, Karl Williamson wrote: I have issued PR13 for fixing this up. One thing I mostly didn't change is the instructions for (k) Porting/mksample. I ran this and immediately regretted it because the changes were so vast from what came before. I think Tux should figure this out. Also, in step (a). This is so confusing to me that i don't know how to clarifiy it.

I too think that step (a) is confusing. IIUC, to have the 'dist' repository -- as distinct from 'metaconfig' and 'perl' -- present on disk is an "advanced user's" thing. If so, then it should be moved farther down in the README and instructions like (b) and (c) that pertain more to the "average user" -- e.g., me at this point -- ought to be moved farther up. However, since I've been working on other post-p5h items, I haven't had time to work thru metaconfig stuff since the hackathon. Thank you very much. Jim Keenan

[khwilliamson]

Also under (k), I don't know what it means to make sure all the developers are happy. Does that mean I'm supposed to buy them a round?

[khwilliamson]

And I don't remember what Tux said about these lines

(i) Check if U/mkglossary (right near the top) points to where you keep
dist's standard metaconfig units as well as your perl-specific ones.

But I don't understand them; perhaps this is why the glossary isn't getting made.

[Tux]

I will re-visit step (a)
@jkeenan I have no objections to you changing README to README.md now that @khwilliamson and I have changed the main flow to current status. Shall I create a new issue and assign that to you?

[jkeenan]

On 10/19/2017 03:58 AM, H.Merijn Brand wrote: I will re-visit step (a) @jkeenan <https://github.com/jkeenan> I have no objections to you changing README to README.md now that @khwilliamson <https://github.com/khwilliamson> and I have changed the main flow to current status. Shall I create a new issue and assign that to you?

I think it's a bit premature to convert README to Markdown. I suspect its content will be undergoing more revision in the next few weeks. I have barely begun to understand how metaconfig works, so much of the content of README is still opaque to me. Hence, my reluctance to fiddle with formatting at this point just to keep our github.com page pretty. Also, note that we have lots of README.* files, all of which are (I think) plain-text. My two guilders. jimk

[Tux]

Does commit 0a071d9 address the confusin you have/had?