Write a notcurses tutorial

[dankamongmen]

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...

[dankamongmen]

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.

[dankamongmen]

we might wanna do this in a way that works well with readthedocs.io, which seems to be the new hotness?

[joseluis]

I don't know about readthedocs, but I like mdbook very much. It uses markdown files and the presentation is superb.

[dankamongmen]

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/

[joseluis]

Yes, most of the big rust documentation endeavours use it... I also like it offers a very handy print button and light/dark themes.

[dankamongmen]

Several people have mentioned the need for this, so let's make sure we get it done for 3.0.

[dankamongmen]

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.

[igo95862]

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.

[dankamongmen]

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:

• Fullscreen vs CLI vs direct mode -- very brief (one para per, max) discussion of the three and easy question-based guide to which one you want. go to either Rendered or Direct section.

Rendered mode

fullscreen mode

• explain alternate screen
• "hello world": draw some colored, centered text, render, wait for a keypress, and exit
• "baby's first media": draw image using cell blitting on standard plane, put text below it, render, WfKP, exit
• "first planes": make text bounce around screen, and show how a plane makes this trivial
• "transparent planes": draw on stdplane, make subplane, subplane is transparent where not filled in ...

cli mode

• start a cli mode program -- show necessary notcurses_init() options
• "hello world": draw some centered, colored text, render, and exit
• "baby's first media": display image, write text below, render, exit
• colorize some subprocess's output, scrollingly ....

Direct mode

• emphasize that direct mode is the unwanted red-headed stepchild of notcurses
• do any truly compelling reasons for using direct mode still exist?

[WSLUser]

Do 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.

[dankamongmen]

yeah CLI mode definitely needs some serious documenting. i added a bit to the FAQs last night but it has no proper writeup.

[esotericist]

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.

[dankamongmen]

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.