-
Notifications
You must be signed in to change notification settings - Fork 4
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
Initial structure of README with some content examples #3
Conversation
Added:
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM
The Contribution Guidelines is not there yet and mabe we can piggy back on the awesome manifesto?
@TallTed thank you for the corrections! Typos and text improvements are accepted without question. But em-dashes don't pass the awesome-lint linter. So I propose we should go with ordinary dashes. |
What development process is the most suitable here?
|
I added a formatting example in the "SHACL Validators" section
Or maybe this one is better?
Unfortunately, all bages in general are out of line with the text 😞 I could not find any way to align it vertically. |
Let's not obsess on details. We can improve gradually |
em-dashes are the correct punctuation where I've put them, where I replaced hyphens, which are not dashes at all. Previously, there were double-hyphens at these locations which are the ancient typist's stand-in for an em-dash on typewriters which didn't have the extra strikers for en-dash (~1.5 hyphens wide) and em-dash (~2 hyphens wide). Clever software replaces such doubled-hyphens with em-dashes en-route to the viewer. (Some extra-clever software replaces double-hyphens with en-dash, and triple-hyphens with em-dash.) Less clever software requires that we humans do the job. I'd like to see the error reported by the not-so-awesome linter, so I can raise an appropriate issue against it. |
Well, that's not awesome! |
@TallTed, I completely agree that em-dash is way better for the readability and overall. But there are two problems (numbered below): The linter's error is:
1 There is even a special check in linter's code List item link and description separated by invalid en-dash or em-dash, which is not throwing this type of error messages in an output stream for some unknown reason. 2 We should also take into consideration that we are planning to submit this list to the community-made aggregators from the issue So, we could end up with attempts to improve all these aggregators. What do you think, @VladimirAlexiev, colleagues? What we should do, the right thing or the easy one? |
The best what could be done with the activity bage vertical alignment (as-before and as-improved). But we need to use HTML tags for the bage instead of a markdown image.
Is it good enough? |
And a bigger list will look like this (the page will be wider)
|
We have two open questions related to this PR: 1. List entry formattingIs this last variant (single dashes, bages alignment, semicolons) acceptable as a starter or not? Should we dump bages or not? 2. The entry content questionRised by @VladimirAlexiev: "We want the link to be most specific, into the SHACL documentation of the concrete product". Should we make a link to the library's documentation a priority compared to a library's repository link? If so, I could replace repo-links with doc-links whenever it's possible. Current variant (shaperone from "Declarative UIs" category)
Doc-links variant (Jena, RDF4J, shaperone changed, others do not have any documentation)
|
I have finalized the last version. It will be rendered like this: |
@amivanoff thanks, you've done a great job! I'm ready to merge, but since you've collected both links, could you make this last change? |
Some punctuation is needed between the license and the language. The single space separator is not sufficient. I suggest the word "license" and a semicolon —
— or the word "license" and a "full stop" —
|
Awesome Linter checks that all list entries have unique links. Complex software like Jena, implements SHACL and ShEx and appears twice in the SHACL Validators and ShEx Validators sections. With doc-links approach it was OK. With repo-links we have a problem. We could use links to the corresponding submodules, but they are not so informative for the reader:
We could use the same "parent" link https://github.com/apache/jena in the SHACL Validators and the ShEx Validators sections but the linter returns an error. Another option, we could use doc-links and clickable badges with URL links to the repositories. But it is difficult to edit. Example of markdown and result rendering for 3 cases:
|
@TallTed, I will add "license" and a semicolon to list entries. |
Does the validation work with links like |
|
…s subitems, docs restored
I fixed all the comments from above. Whenever possible, I used shield.io badges for versions and last activity dates because this eliminated the necessity for manual updates. |
Great job @amivanoff ! I'll merge it but first want to pick up all links mentioned, eg by @bergos. |
@VladimirAlexiev, Thanks! |
README with the Contents and initial structure of sections.
Some sections entries migrated from Updated list of implementations as an examples. It is not a complete migration, just an illustration.
Closes #1