Akkarin Posted June 28, 2016 Group: Forum Manager Topic Count: 282 Topics Per Day: 0.06 Content Count: 3123 Reputation: 1617 Joined: 03/26/12 Last Seen: Monday at 09:28 PM Share Posted June 28, 2016 As we've been using Github for a while now, do you think that files included in the repo should be brought upto modern standards? May as well take full advantage of the tools we already use. I'm talking about /doc/ and the samples folder. Github has this marvellous markdown capability and we're pretty much ignoring it. The only place it's used is in Readme.md, and we even have a .txt variant of that for no reason whatsoever. Updating /doc/ to use Markdown will provide us with the ability to link directly to files/lines within the repo, include snipets, hyperlinks, even example images for users viewing the docs via github itself. It just seems such a waste to have those monstrous text files gathering dust when we can be using them for so much more. And before anyone comes up with some cynical ".md extension" rubbish, .md can be read by all text editors too. And via the web. And is still readable in plain-text format for "backwards users compatibility". So no excuse really. Quote Link to comment Share on other sites More sharing options...
Emistry Posted June 28, 2016 Group: Forum Moderator Topic Count: 93 Topics Per Day: 0.02 Content Count: 10013 Reputation: 2348 Joined: 10/28/11 Last Seen: April 6 Share Posted June 28, 2016 something that would look like this within one file ?https://github.com/HerculesWS/Hercules/blob/master/doc/constants.md Quote Link to comment Share on other sites More sharing options...
Akkarin Posted June 28, 2016 Group: Forum Manager Topic Count: 282 Topics Per Day: 0.06 Content Count: 3123 Reputation: 1617 Joined: 03/26/12 Last Seen: Monday at 09:28 PM Author Share Posted June 28, 2016 something that would look like this within one file ? https://github.com/HerculesWS/Hercules/blob/master/doc/constants.md Jesus that file is heavy... And no, that's a pretty ridiculous reason to move to markdown. All it's using is just unordered-lists. In that particular example i would suggest adding a constants/ dir to /docs/ and separating some of those groups in order to expand, link, describe, example usage, etc. Just adding list options to a big-ass list like that is a waste of time. Quote Link to comment Share on other sites More sharing options...
Capuche Posted June 28, 2016 Group: Developer Topic Count: 10 Topics Per Day: 0.00 Content Count: 2407 Reputation: 613 Joined: 07/05/12 Last Seen: April 15 Share Posted June 28, 2016 Hmm we need to make a sample. Quote Link to comment Share on other sites More sharing options...
Aleos Posted June 28, 2016 Group: Development Manager Topic Count: 56 Topics Per Day: 0.01 Content Count: 732 Reputation: 525 Joined: 12/13/11 Last Seen: August 14, 2023 Share Posted June 28, 2016 I agree. It would be great to port over to a standard markdown. Linking across Github would be a great feature with it as well. It could also pose a great effort in the revitalization of the Github wiki so rAthena can drop it's end of the wiki and start focusing on just being a forum again. Quote Link to comment Share on other sites More sharing options...
Akkarin Posted June 29, 2016 Group: Forum Manager Topic Count: 282 Topics Per Day: 0.06 Content Count: 3123 Reputation: 1617 Joined: 03/26/12 Last Seen: Monday at 09:28 PM Author Share Posted June 29, 2016 Hmm we need to make a sample. Samples incoming Aleos don't beat me to the punchline, this is a stepping stone to sorting out the wiki once and for all. This is a very basic example. Not really much to do with this file but chose it as it's small and something i could whip up quite quickly: https://github.com/Akkarinage/rathena/blob/docupdate/doc/map_cache.md Quote Link to comment Share on other sites More sharing options...
Emistry Posted June 29, 2016 Group: Forum Moderator Topic Count: 93 Topics Per Day: 0.02 Content Count: 10013 Reputation: 2348 Joined: 10/28/11 Last Seen: April 6 Share Posted June 29, 2016 uhm, but when it come to the script_commands.txt its gonna be a god damn long and heavy contents. if rAthena decided to remain every single script command within same text files, then it probably end up like the sample from Herc I shown above. if rAthena decided to separate each script command into their own individual .md files, it look short/simple/nice, but it lose the convenience where you can find all script command within 1 text files especially when you try to view it in any text editor. Quote Link to comment Share on other sites More sharing options...
Akkarin Posted June 29, 2016 Group: Forum Manager Topic Count: 282 Topics Per Day: 0.06 Content Count: 3123 Reputation: 1617 Joined: 03/26/12 Last Seen: Monday at 09:28 PM Author Share Posted June 29, 2016 script_commands.txt will always be a challenge. We can't break it up, but it needs a damn good sort through. There's command descriptions that are outdated, incorrect and poorly worded. That being said, I have a plan and will get a test commit pushed soon 1 Quote Link to comment Share on other sites More sharing options...
Skorm Posted June 29, 2016 Group: Forum Moderator Topic Count: 33 Topics Per Day: 0.01 Content Count: 1268 Reputation: 382 Joined: 02/03/12 Last Seen: Sunday at 08:12 PM Share Posted June 29, 2016 I'm going with the current minority on this one... [|||] Pro: I like the idea of optimizing things. Hyperlinks are cool. Engrish is sometimes mistakenly used in the old documents. [|||] Con: I've been using the old text documents for years with no problems. I'm probably the only one here that thinks this, but I don't hate the Wiki. I don't like the idea of loading a webpage everytime I want to view something. Windows doesn't natively know what to do with .md files creating another barrier for beginners... (I can already hear the support leaders cries.) Editing our documents becomes more convoluted. Quote Link to comment Share on other sites More sharing options...
Secrets Posted June 30, 2016 Group: Developer Topic Count: 36 Topics Per Day: 0.01 Content Count: 587 Reputation: 431 Joined: 01/26/16 Last Seen: April 16 Share Posted June 30, 2016 I'm going with the current minority on this one... [|||] Con: I've been using the old text documents for years with no problems. I don't like the idea of loading a webpage everytime I want to view something. Windows doesn't natively know what to do with .md files creating another barrier for beginners... (I can already hear the support leaders cries.) Editing our documents becomes more convoluted. 1. Old one being fine doesn't mean that it can't be improved. 2. Markdown is supposed to be human readable even in its plain text format. 3. If they don't know how to open a .md file using text editor they might as well as shut their server down. 4. You can just copy-paste the template from another command. 1 Quote Link to comment Share on other sites More sharing options...
Skorm Posted June 30, 2016 Group: Forum Moderator Topic Count: 33 Topics Per Day: 0.01 Content Count: 1268 Reputation: 382 Joined: 02/03/12 Last Seen: Sunday at 08:12 PM Share Posted June 30, 2016 1. Old one being fine doesn't mean that it can't be improved.2. Markdown is supposed to be human readable even in its plain text format. 3. If they don't know how to open a .md file using text editor they might as well as shut their server down. 4. You can just copy-paste the template from another command. I'm not saying you're wrong, but you'd be surprised. (As I side note I did look over the RAWs from the sample and they looked readable... Although my position is still neutral.) Quote Link to comment Share on other sites More sharing options...
Lemongrass Posted June 30, 2016 Group: Developer Topic Count: 28 Topics Per Day: 0.01 Content Count: 547 Reputation: 270 Joined: 11/08/11 Last Seen: 21 hours ago Share Posted June 30, 2016 It would be nice to see some real samples of markdown to be honest. You stated linking lines etc is possible. As for script_commands.txt: In my opinion this file should become an overview file, which links to subdirectories/subfiles for each chapter + each command. Each command should also contain or even better link/include a reference sample script. Additionally it would be good to also get some test cases for each command to be able to ensure that it is still working. But this is a different story. Quote Link to comment Share on other sites More sharing options...
Akkarin Posted June 30, 2016 Group: Forum Manager Topic Count: 282 Topics Per Day: 0.06 Content Count: 3123 Reputation: 1617 Joined: 03/26/12 Last Seen: Monday at 09:28 PM Author Share Posted June 30, 2016 It would be nice to see some real samples of markdown to be honest. You stated linking lines etc is possible. As for script_commands.txt: In my opinion this file should become an overview file, which links to subdirectories/subfiles for each chapter + each command. Each command should also contain or even better link/include a reference sample script. Additionally it would be good to also get some test cases for each command to be able to ensure that it is still working. But this is a different story. Most of the commands in script_commands.txt already have example usage scripts in the doc itself. I don't see why we can't have specific script samples in the /doc/samples/ dir, as that's what it's there for. However, I don't think breaking the file up into grouped commands is a good idea. Quote Link to comment Share on other sites More sharing options...
Kurofly Posted July 1, 2016 Group: Members Topic Count: 31 Topics Per Day: 0.01 Content Count: 283 Reputation: 31 Joined: 07/08/14 Last Seen: January 15, 2022 Share Posted July 1, 2016 Doesn't seem like a really good idea to me.. Sure I'd love to see .md files as documentations and it's true that we have some monstrous doc files. But that's gonna take a hell lot of time! A big effort has already been put by devs to make the plain texts as easily readable as possible, I personnaly find it easy to read and people are already used to them. Since there are way more people used to those files than people who are not (not 100% sure of that though ^^) I'd say this amount of work is not really worth it There's also one thing I'm afraid of, if you look at the file emistry posted, to me it looks even more horrible than it looked before! Bulleted lists are nice but it becomes a pain when there are too many of them. I'd especially pay attention to that because if you considerer some files monstrous that's definitely something you should avoid. Even so, links, bold texts, and text size would be some really cool features to see in doc files. It all depends on the way it's done, it can be really nice but one thing for sure is that it's gonna take muuuuuch time, that's why I'm a bit reluctant to this idea. Quote Link to comment Share on other sites More sharing options...
Cydh Posted July 26, 2016 Group: Developer Topic Count: 153 Topics Per Day: 0.04 Content Count: 2285 Reputation: 745 Joined: 06/16/12 Last Seen: June 30, 2023 Share Posted July 26, 2016 It'll be good... or not. Only if I can open markdown file in 'pretty view' locally (except Chrome extension). 3. If they don't know how to open a .md file using text editor they might as well as shut their server down. TL;TR Mark down file will be pretty good of Github integration, but not for local usage, but still I want to see the docs are human-readable. Well, just make README.md on /doc/, wite summary there, HIRE SOMEONE AS DOC MANAGER then whip them to make .md version of all rAthena docs, put the links on /doc/README.md, uploa dthe .md docs on different repo :v 1 Quote Link to comment Share on other sites More sharing options...
Recommended Posts
Join the conversation
You can post now and register later. If you have an account, sign in now to post with your account.