Simpler, markdown README #756
Conversation
|
Hopefully not mercilessly, but I was wary of markdown fitting into all the various cpan & related systems out there. I got bitten by some "indexer" being extraordinarily picky about things. And besides, while markdown may be cleaner than POD, they're both extra markup stuff that you've got to remember. I tried to please by at least not using the standard (& annoying) POD headings... I think all the extra widgets you're requesting can be done using slightly cruftier POD markup. Although I'm still inclined to put them lower (under Status) than higher. |
|
If we can turn off the really annoying heading links in the POD, that would be amazing. I couldn't find a way to do that. |
|
As to CPAN, i am 100% certain it can accept README.md files, maybe with some extra configuration? The latexmls plugin got indexed without any problem with a README.md. And I am pretty sure Mojolicious is indexed perfectly, with a README.md. I know markdown is yet-another-markup-language to learn, but all of us know it. Wikipedia is mainstream, and github comments use it extensively, so it has become expected to be known by devs my age or younger. And I would assume "most devs" nowadays. |
|
Ironically, I keep arguing online why latex is still relevant, in an age of markdown dominance for most open source documentation, see this hackernews thread for an example |
|
On 06/04/2016 11:33 AM, Deyan Ginev wrote:
Well, you're completely right there; that's the proper solution. |
|
README.tex will definitely raise a LOT of eyebrows 👍 Not even latex's CTAN uses such dark arts, their readmes are plaintext. But if we convince GitHub to render README.tex with latexml, wouldn't that be an awesome development? |
|
hmm... not sure I want to do this, and I can't even rationalize why! As for the headers being links, the 1st one is intentional, but if I can't come up with a way of making the others be non-links, I could at least have them point to something sensible (eg. mailto:me for the Author; dunno what for the license) |
|
My main issue is that the links as headers will chase new people away from the page, since this is very untypical for a GitHub repo. It's almost as if the page got mangled somehow. I personally also find it ugly :> README.md is likely ubiquitous as a readme syntax over here, so... I'm still pushing for it. Let me know if there is another way to convince you. FWIW, I did try to read through the POD documentation in some depth, looking for a way to disable the link behaviour for headings - I couldn't find one... sadly. |
|
Ugly!?! You only see that it's a link if you hover over it -- and then you get underlining; OMG!! It's only ugly in that the headings are big and bold, just like your markdown version. And your version has scary links too and scary link icons! I like that "LaTeXML" is a link to the homepage; I did that on purpose! |
|
Side by side:
To me, and anyone really, this shade of blue screams "link" out loud. And to me personally, seeing links as headings is something that feels very iffy, and not particularly visually appealing. Bold headings are just standard, and they look quite regular. Sorry, I've probably exhausted my quota of shareable opinions for the day, but I just like the non-link headings a lot better. |
|
Oh, yeah, blue... didn't even notice. But then I'm used to blue; not scared by it at all. |
|
I am not questioning your bravery, just the general appeal of your weapons of choice :> Being a "model github project" gives latexml that extra freshness it needs to attract those up-and-coming 20 year old hackers. |
|
mergeable? |
|
Well, while I really do appreciate the effort, I'd just as soon not anger the ghost in the CPAN machine. Although markdown might be fine, why yet-another, since we've already got to deal with POD in all its ugliness anyway? And while attracting impressionable young whippersnappers is a good thing, they won't be happy without a well honed ability to pinch their noses. Why not impress them with the idea that: Hey, you can even do almost tolerable things with Perl! For all that, I did take your cues and freshen it up a bit, while remaining POD: more whitespace; the unnecessarily linked headings are now gratuitously linked to something almost sensible. Take a look! |
|
If I can not convince you to share my dread of "links in headings", the rest of the improvement is probably not worthwhile. It doesn't help that you actually like links in headings, which I find shocking. But given we have the super awesome badges already, I can't be too unhappy. I'll try sneak in the markdown README some other day when you're not paying close attention I guess. Thanks for considering it! |
|
On 07/03/2016 07:13 PM, Deyan Ginev wrote:
That's the way to do it! :> |
|
On 07/03/2016 07:13 PM, Deyan Ginev wrote:
Incidentally, the links seem(ed) to point somewhere pointless If you want to pursue it on that end, and get it "fixed", |
|
I pursued it prior to going to markdown, I only tried the MD way after convincing myself it's impossible with the POD support. |
If you give a mouse a cookie... It will ask you for some markdown! Thanks for accepting the #755 PR.
I have a tentative proposal for what I find to be a much prettier + compact README.md file. You can view it here:
https://github.com/dginev/LaTeXML/blob/markdown-readme/README.md
In the case where I get mercilessly shutdown, I would alternatively want to ask about the reasons why the markdown solution is considered unfeasible. The main motivation for me to embark this route was rooted in the really annoying (to me) mandatory links for any POD
=headelement. It's just so... ugly.I'm eager to do any further work/readme research if there are more knobs to turn.