search

tukaani-project / xz

XZ Utils
https://tukaani.org/xz/
Other
503 stars 40 forks source link

A reborn of the project with Markdown based docs #106

Closed KRTirtho closed 2 months ago

KRTirtho commented 3 months ago

First of all, I'm really sorry for what happened, and the original author didn't deserve all this.

XZ is a modern tool (2016 first release I think?) yet all docs is in ASCII text files. While I admire and fond of good old plain ASCII text, but we also shouldn't let the chance of utilizing the modern Markdown features slip.

Currently, I've added the markdown only for README (old one's intact). If I get a green-light, I might also convert other ASCII plain text files into Markdown (while keeping the ASCII one's of course).

I'm creating this PR as a draft, as only README is in Markdown and not every docs' file.

Also, best of luck. I (and many others) believe in this project.

thesamesam commented 3 months ago

XZ is a modern tool (2016 first release I think?)

2009 :)

Before that, it was lzma-utils too.

Thank you for your kind words. It may take some time before we can get to regular PRs as the auditing work is continuing. Patience is appreciated.

KRTirtho commented 3 months ago

2009 :)

Before that, it was lzma-utils too.

Wow, looks like I did not know the full history. Thanks for letting me know.

It may take some time before we can get to regular PRs as the auditing work is continuing. Patience is appreciated.

Yes, please take as much as time you need. I'll keep it as a draft, and will get back to it as soon all auditing work is done.

Good luck and this project is much appreciated ❤️

qwertychouskie commented 3 months ago

(while keeping the ASCII one's of course)

Markdown is designed to be readable as ASCII, keeping two slightly different copies of documentation around is just going to result in desyncs and is probably not worth the effort.

Larhzu commented 2 months ago

First of all, I'm really sorry for what happened, and the original author didn't deserve all this.

Thank you for the nice words!

Wow, looks like I did not know the full history.

There is history.txt in the repository although it isn't very up to date. The latest commit is from 2012.

keeping two slightly different copies of documentation around is just going to result in desyncs

Yes, two copies isn't the way to go.

I understand that Markdown gives fancier look when viewing the files on GitHub but I like traditional plain text files in this kind of projects. They look slightly nicer than Markdown when viewed as is outside GitHub. The contents of the files, including README, likely need updating to their contents though.

Thus, I thank you for the effort but this isn't planned for now.

qwertychouskie commented 2 months ago

You can make the document valid Markdown while still having the raw text look extremely similar: https://gist.github.com/qwertychouskie/d5aad4810de1b8b1c3ce20ac51015170

Larhzu commented 1 day ago

You can make the document valid Markdown while still having the raw text look extremely similar:

Yes, that's a strength of Markdown.

I converted files in XZ for Java in a way that keeps plain text look decent. I tried to keep it as CommonMark without extensions although GFM seems to be quite widely supported in practice.

I'm not in a hurry to do such a conversion in XZ Utils. The content of the docs should be looked at first. I don't have much clue how many tend to view files like README and INSTALL via a Markdown renderer and how many read plain text versions. I know I read such files locally and appreciate if they are optimized for readability instead of editability. ;-) Also, I suppose XZ Utils and XZ for Java have slightly different sets of users.