README or README.md ?

[cdlm]

STIG saves README but the Cypress-Mocks repo (#7) contains README.md. What about the inevitable README.TXT or ReadMe.html?

I guess either we decide that GitHub-flavored README.md is the one and only, or we follow GitHub's precedence rules (not sure what they really are, but see this related issue)

Corollary: what should be the preferred name for saving class comments, in the absence of a hint from the user?

[krono]

GitHub would render README as plain text with no way to convince it of other ways.
That way, README.md would be nice.

If, however, GitHub et al. were to convince to render README as Markdown (or something at all), I'd go for README.

[dalehenrich]

The original intent was to go with README.md so that you could use MarkDown, but there aren't a lot of class comments that are written in MarkDown and those can look pretty ugly .... so README it is ...

[cdlm]

My preference goes to Markdown.

I initially had the objection that for this to be done the right way, the format of class comments should be modeled somewhere, instead of them just being Strings (and therefore, plain text README or README.txt) or Texts (README.html).

But one of the points of Markdown is that when there is little markup, it just disappears; paragraphs and bullet lists are just what you'd do in plain text, for instance. Therefore, most current class comments are actually Markdown without knowing it, and I'm not convinced there are that many class comments that would render badly if interpreted as Markdown.

[dalehenrich]

My first preference was markdown, but in fact there are some pretty bad looking comments out there when interpreted in markdown, so I didn't push it

At the end of the day, it's the image-based tools that are more important so when a markdown viewer shows up then markdown can be used in the class comments...

[krono]

In fact, there are several classes in Squeak that use Text as class comment, using

• http-URLs
• clickable references to other classes and methods
• text formatting such as emphasis or color.

These could be rendered to Markdown.

[cdlm]

Ok, fair enough.

[krono]

Actually,

If there is a README.*, take the first[1] of possibly multiple matching files.
Else, expect a README to exist.

Implementations should be free to, e.g., read a README.md into a Text object.

[1]: Whatever first means. For simplicity I'd opt for alphabetically.

[cdlm]

The actual problem is 2-fold:

• if there are several files, which one to read as the class comment (your proposition works here)
• if we're writing the class comment for the first time, how to name the file? If the comment is a String, nothing indicates if it's plain text or markup or an in-between (here I think the tools need a notion of project-specific settings, or the browser should allow to pick the markup syntax of the class comment)

Also, rendering Texts into Markdown is only possible in simple cases. Markdown does not do color or fonts, for instance. A more correct mapping would be to HTML.

[krono]

@cdlm completely agree. I don't think github would render HTML, tho, does it?

[dalehenrich]

My inclination is to take things a bit slowly ... part of the reason I asked @cdlm to do the Cypress implementation from scratch is that the old FileTree implementation became overly complex because it was supporting 5 or 6 different formats and the code itself get's complicated pretty quickly ...

My experience with markdown, is that I don't like to actually read it without a reader and I don't have a reader in tODE, so markdown makes things harder to read at that point:) ...

This is a multi-platform/multi-implemetation project, so we have to make sure that all implementations do the same thing otherwise we are unable to share code ...