Open dankamongmen opened 4 years ago
I think we should start work on this immediately following declaration of a stable API -- and not before then. We already have to update the book for changes since the 1.2 era. I don't want a bunch of obsolete tutorials out there.
And on that note, we ought make #627 a priority.
we might wanna do this in a way that works well with readthedocs.io, which seems to be the new hotness?
I don't know about readthedocs, but I like mdbook very much. It uses markdown files and the presentation is superb.
I don't know about readthedocs, but I like mdbook very much. It uses markdown files and the presentation is superb.
ahhhh yes i've seen this, so this is what's being used for e.g. https://doc.rust-lang.org/book/
Yes, most of the big rust documentation endeavours use it... I also like it offers a very handy print button and light/dark themes.
Several people have mentioned the need for this, so let's make sure we get it done for 3.0.
I'm on vacation this week, and thinking maybe I can take a day or two to get a first draft out.
@joseluis, @igo95862, @MasFlam , anyone else who would like to comment: what needs be covered? in what order? what thoughts have ye?
if i write this according to my own notions, it'll start off with like, physics, and end with a discussion of programming language theory, and somewhere i'll mention that you can use colors.
Can you start the tutorial slow? "Hello, World" is pretty good starting point. I scrolled through the book and it immediately jumped to pretty complex topics. When introducing a new topic try to make example as simple as possible.
alright some work should get done on this in september and october. here's what i'm thinking, content-wise; i'm fighting very hard my tendency towards the abstract and theoretical and axiomatic, and instead focusing on getting-some-shit-down-on-editor:
notcurses_init()
optionsDo you think you could make it easier to know what parts are specific to cli mode? I want to get a couple terminal applications to adopt notcurses but they don't necessarily have a TUI. I think cli-mode would likely still be useful if I understand it correctly.
yeah CLI mode definitely needs some serious documenting. i added a bit to the FAQs last night but it has no proper writeup.
i waffled between opening a new issue and commenting here as the apparent closest open issue, apologies if i picked wrongly, but is there any chance of an html export of the guidebook? the pdf is pretty difficult for me to work with due to accessibility needs, and i'd hope that the authoring format you used would make it plausible.
no worries for bringing it up here. the guidebook is in LaTeX and i can probably make it spit out html, though i can't speak to the quality. it might also be almost completely impossible. hard to know with LaTeX.
It would be useful to have something less daunting than the book, and yet more structured than the man pages and USAGE.md. A tutorial of some number of quick lessons, with examples, seems called for. I'd think we'd want to introduce first direct mode, then styles/colors in the standard plane + base char, then multiple planes, then transparency, then...