Revamp the docs using minimalistic markdown#10545
Revamp the docs using minimalistic markdown#10545mspncp wants to merge 16 commits intoopenssl:masterfrom
Conversation
mspncp
changed the title
|
this is way cool. |
|
What about the CHANGES file? Ideally, it should be revamped the same way as the NEWS file. |
Sure, I intend to convert all those files to markdown. Since the conversion of the CHANGES file will be very similar to the one of the NEWS file, I did not bother to do it for the preview yet. Most of the other file conversions will be straightforward, too. The only file which currently gives me headaches is the INSTALL file, because of its table structure for the options. I don't see how I could mimick this in markdown without raw HTML. So I'll have to think of a different way to format the text which looks equallly well in both views. |
|
Apropos NEWS & CHANGES: did you see that I added the entire history back, taking the missing peaces from the stable branches? So in the future the files on 1.1.1 LTS will just be a shortened copy of the ones on master (if we backport the reformatting, which we probably should). We could utilize this fact to simplify cherry-picking from master to 1.1.1 in the future: those files will always conflict, but we can just run a script which accepts the incoming version from master and drops all entries newer than 1.1.1. |
I actually view that as a definition list, which exists as an extended syntax... one might argue about the readabilty of colon-prefixed lines, though... |
|
_(quoted from #10546 (comment))
If you see it like that, it's ok for me. Maybe a good compromise would be to have a single NOTES file with a Table of Contents? |
So the user will have to scroll past lots of text to get to their specific pet peeve? |
Thanks for the link to markdownguide.org, which was new to me. I'll take a look at it. I am familiar with simple tables, but tables containing paragraphs and other items like fenced code blocks are a completely different matter. They will always look ugly in raw text. |
mspncp
force-pushed
the
revamp-the-docs
branch
from
fdefe3c to
980cd04
Compare
CHANGES.md
Outdated
There was a problem hiding this comment.
Use backquotes around __owur. This starts a looooooooooooooooooooong bold chunk of text
There was a problem hiding this comment.
Hmmm... there is only a single __owur in the text and that looks perfectly normal. Are you using a different markdown viewer?
There was a problem hiding this comment.
Note: the CHANGES file contains a lot more text than the NEWS file, so I did not manage yet to go through the entire text and spot all formatting issues.
|
Started working on the INSTALL file:
|
mspncp
force-pushed
the
revamp-the-docs
branch
2 times, most recently
from
7fcd715 to
6924714
Compare
|
Just autosquashed some commits without changing anything. |
mspncp
force-pushed
the
revamp-the-docs
branch
from
6924714 to
ad4102b
Compare
The INSTALL fileThe latest update contains some initial work on the INSTALL file. In particular the Configuration Options section gave me a hard time, because the original two column layout of the text file is not reproducible in markdown. I tried to find a reasonable compromise which looks acceptable in both versions. As usual, you need to look at both versions:
|
|
Note: rebasing this pull request to fix conflicts is practically infeasible because of all the whitespace changes. Since the changes on master are negligible compared to those on my branch, I will incorporate the changes from master manually in the end. |
mspncp
force-pushed
the
revamp-the-docs
branch
from
ad4102b to
3ba2247
Compare
After having sufficient sleep, rebasing was not that infeasible anymore. The trick is to manually compare stage 1 (BASE) of the conflicting file with stage 2 (OURS: master) and then integrate those changes manually into stage 3 (THEIRS: revamp-the-docs). Here is what I did for CHANGES.md: |
mspncp
force-pushed
the
revamp-the-docs
branch
from
24e77d8 to
0f73eb0
Compare
Unfortunately GitHub Flavoured Markdown does not support definition lists. |
mspncp
force-pushed
the
revamp-the-docs
branch
from
f2c5b9b to
5f93b53
Compare
I think this is looking really nice. It seems to work in both formats. |
Thank you very much, Matt. I think that, except for the SUPPORT file, all files have already matured so far that an initial review would be possible. There are some more files which I didn't start on yet, but maybe it's better to keep them for a followup pr. That's why I'll change the prefix from [PREVIEW] to [WIP]. |
mspncp
changed the title
t8m
removed
the
approval: review pending
|
Still approved. @openssl/committers please speak up if you have any objections. |
mspncp
added
approval: ready to merge
In the first step, we just add the .md extension and move some files around, without changing any content. These changes will occur in the following commits. Reviewed-by: Tomas Mraz <[email protected]> (Merged from #10545)
The goal is to transform the standard documents
README, INSTALL, SUPPORT, CONTRIBUTING, ...
from a pure text format into markdown format, but in such a way
that the documentation remains nicely formatted an easy readable
when viewed with an normal text editor.
To achieve this goal, we use a special form of 'minimalistic' markdown
which interferes as little as possible with the reading flow.
* avoid [ATX headings][] and use [setext headings][] instead
(works for `<h1>` and `<h2>` headings only).
* avoid [inline links][] and use [reference links][] instead.
* avoid [fenced code blocks][], use [indented-code-blocks][] instead.
The transformation will take place in several steps. This commit
introduces mostly changes the formatting and does not chang the
content significantly.
[ATX headings]: https://github.github.com/gfm/#atx-headings
[setext headings]: https://github.github.com/gfm/#setext-headings
[inline links]: https://github.github.com/gfm/#inline-link
[reference links]: https://github.github.com/gfm/#reference-link
[fenced code blocks]: https://github.github.com/gfm/#fenced-code-blocks
[indented code blocks]: https://github.github.com/gfm/#indented-code-blocks
Reviewed-by: Tomas Mraz <[email protected]>
(Merged from #10545)
Reviewed-by: Tomas Mraz <[email protected]> (Merged from #10545)
* Add an OpenSSL logo and CI badges * Add a table of contents * Add a lot of links Reviewed-by: Tomas Mraz <[email protected]> (Merged from #10545)
Up to now, NEWS entries for older releases where only added to the corresponding stable branches, so they were missing in the master branch. This commit adds the missing entries, taking them from the respective stable branches. Reviewed-by: Tomas Mraz <[email protected]> (Merged from #10545)
Up to now, CHANGES entries for older releases where only added to the corresponding stable branches, so they were missing in the master branch. This commit adds the missing entries, taking them from the respective stable branches. Reviewed-by: Tomas Mraz <[email protected]> (Merged from #10545)
Reviewed-by: Tomas Mraz <[email protected]> (Merged from #10545)
Too be continued... Reviewed-by: Tomas Mraz <[email protected]> (Merged from #10545)
Reviewed-by: Tomas Mraz <[email protected]> (Merged from #10545)
|
Done. Thanks for the feedback! c50604e doc: add a fancy CHANGES entry to celebrate the new Markdown format |
| <!-- Logos and Badges --> | ||
| <!-- | ||
| Note: The security token for the appveyor badge (the random number in | ||
| the URL below) was obtained for the mspncp/openssl project. | ||
| It needs to be replaced by the correct token by some core member | ||
| (@levitte, @mattcaswell?). It can be obtained for project members at | ||
| https://ci.appveyor.com/project/openssl/openssl/settings/badges. | ||
| --> | ||
|
|
There was a problem hiding this comment.
You just need to mail me the token, I can open the pull request.
The AppVeyor badge was still showing the build state for the mspncp/openssl fork. This commit fixes a forgotten todo from openssl#10545.
The AppVeyor badge was still showing the build state for the mspncp/openssl fork. This commit fixes a forgotten todo from #10545. Reviewed-by: Matt Caswell <[email protected]> (Merged from #12361)
The AppVeyor badge was still showing the build state for the mspncp/openssl fork. This commit fixes a forgotten todo from openssl#10545. Reviewed-by: Matt Caswell <[email protected]> (Merged from openssl#12361)
Formatting is still very mixed in the NOTES and README files. This commit tries to make formatting more consistent with the one introduced in pull request openssl#10545.
Formatting is still very mixed in the NOTES and README files. This commit tries to make formatting more consistent with the one introduced in pull request #10545. Reviewed-by: Paul Dale <[email protected]> (Merged from #14042)
6 participants
The Landing Page
On GitHub the README file of a project serves as its landing page, it is displayed immediately below the directory listing. Currently, the OpenSSL README is a raw text file, which gives a rather dusty impression, compared to all these fancy landing pages you find nowadays on GitHub.
Current Landing Page
This is how our landing page looks currenty.
New Landing Page
Wouldn't it be much nicer if it would look something like that?
For a long time I've dreamed of such a fancy landing page, but it turned out not to be so easily done.
The Problem
My first attempt to replace the simple text README file by a fancy markdown file ended up in a file which was not very well readable anymore in a text editor. This was a serious disadvantage for developers downloading the source tarball and trying to get started.
One possibility to avoid this problem would have been to add a separate markdown version of the README file as
.github/README.md, which would have been favoured by GitHub. But having two different README files is not really a good solution. After trying different options for several weeks, the solution to the problem came to my mind.Minimalistic Markdown
The idea is to have a single README file which does not only look pretty when viewed in the browser, but is also well formatted and easy to read when you view the raw file in your favourite text editor. Wasn't that exactly the goal of the original markdown implementation of John Gruber und Aaron Swartz? So I tried to go back to the roots using minimalistic markdown.
With 'minimalistic' markdown, I don't mean a certain markdown dialect. It's just the fact that I try to add as little markup as possible, which could interfere with the reading flow int the text file.
For example,
<h1>and<h2>headings only).Show Cases
The Landing Page
I changed the default branch of my repository clone mspncp/openssl to the
revamp-the-docsbranch, so you can view my changes there live in action. The following files have already been heavily revamped or are currently in progress. Please take a look at them and compare their online version with their raw file content.The README file
The NEWS file
The CHANGES file
The INSTALL file
The SUPPORT file
Your feedback, please!
This work is currently an early draft. So instead of diving into the documents and looking for typos and whitespace errors, I'd rather appreciate if you could give me more high level feedback, for example:
Looking forward to your comments!