Why isn't there a basic code sample or tutorial?

[jokoon]

I understand that:

• it's an experiment
• it is not stable and meant for use
• it's constantly changing and evolving

But I wish I could just learn the basics, even if everything is subject to change and if the cpp2 I write now has a 100% risk to be invalid code in the future.

There could be a short tutorial with basics and so on, with a BIG RED WARNING that it's not final.

I also understand that since C++ is large, thus cpp2 semantics can also be quite complicated to explain thoroughly.

Right now the regression tests seem quite fastidious to read as doc.

Personally, I'm really excited about cppfront, but apart from the cpp talks there are not (I think) things I can read about how to right this new syntax.

Having a short syntax summary might help a bit to toy around with it.

[msadeqhe]

I think it would be great if there was a markdown file for documentations in this repository, and we could contribute to it. There are many learning stuff from discussions, issues and commits. They could be gathered in one place as Cpp2's documentation.

[ntrel]

For a while I've been working on an overview of Cpp2, available here:
https://github.com/ntrel/cpp2#readme

[jokoon]

Ah thanks, that's great

[realgdman]

Folder with https://github.com/hsutter/cppfront/tree/main/regression-tests worth digging, for example
https://github.com/hsutter/cppfront/blob/main/regression-tests/pure2-intro-example-three-loops.cpp2
https://github.com/hsutter/cppfront/blob/main/regression-tests/pure2-types-basics.cpp2
https://github.com/hsutter/cppfront/blob/main/regression-tests/pure2-inspect-expression-in-generic-function-multiple-types.cpp2

[JohelEGP]

From #650 (comment):

I also presented the above five general areas I'm planning to do work on, and polled the room on "if you could pick just two of those five, which would they be?" and the results were:

• Clear winner: Writing a Cpp2 user's guide. That's something I'd planned for later, but I hear the feedback that I should prioritize it sooner.

Another place where documentation has been discussed is 258190e#commitcomment-103478383.

[lauler1]

I've initiated a tutorial on Cppfront within my GitHub repository: https://github.com/lauler1/cppfront/tree/main/tutorial.

Currently, only Part I (Basics) is available. While it's not fully polished, the foundational structure of the tutorial is in place. I warmly invite you to explore, provide feedback, and even contribute if you're interested.

Your insights and contributions would be greatly appreciated. Thank you!

[JohelEGP]

This is now a discussion: #775.

[hsutter]

Docs are finally on the way! https://hsutter.github.io/cppfront/

These are the three pages:

• ✅ Overview & getting started — initial version complete
• 🚧 Cpp2 reference — initial version 1/3 complete
• ✅ Cppfront reference — initial version complete

I decided to try using @squidfunk's MkDocs Material with GitHub Pages and I love it. Thanks, Martin!

Things I love:

• It's beautiful.

Fine, I'm (a) a sucker for beautiful things (especially typography) and (b) a control freak when it comes to making sure my writing looks the way I like. That's the main reason I did all the typesetting (and indexing) for my third and fourth books. Well, that plus Scott Meyers shamed me into it, especially the indexing part.

Zooming a little:

Dark theme:

Okay, a little more detail about things I love:

• Great Markdown support, with extensions to let code blocks have titles and highlight specific lines, and most of all a default cpp colorizer that's beautiful for Cpp2 including especially for Cpp2's identifier : declarations. It has always been important to me to have a colorizer that makes identifier : pop, because names matter and it was a specific design goal to make name declarations very visible in the plain syntax and easy to grep, and I want them to pop in the colorizer too.
• Search with nice previews.
• The left side navigation sidebar (if you don't see it, hit Ctrl-minus or widen your window). To me it was immediately indispensable... it gives a great overview of the page's contents as well as the ability to navigate.
• Light/dark theme (see toggle at top right), both beautiful. I often don't like dark themes, but I like this one.
• It was actually pretty easy to configure, thanks to @james-willett's excellent YouTube tutorial. It's a model tutorial video. But enough fanboying... thanks again, James.

If I sound little giddy, it's because I insist that docs look good, and I'm no GitHub/web expert so I kind of dreaded figuring out how to make cppfront docs look good. I didn't expect to get a result nearly this nice. Exceeds expectations, would buy again. 👍

@gregmarr and anyone who would like to contribute can do so by submitting PRs to the docs branch (not to main).

[squidfunk]

Glad you like and support my work! We're working hard to make it even better in 2024 🚀

[hsutter]

@squidfunk Thanks again!

Say, if I can abuse your availability slightly while I have you, but please ignore this unless it's a super quick answer: Is there a way to make the left navigation pane stay visible at slightly higher browser Zoom levels / narrower browser windows? For the first screenshot above, when I hit Ctrl-+ just one more time or narrow the window slightly, there's still plenty of empty space on the right in the main text, but the navigation pane disappears, which is sad because it's so super useful. (I looked in the docs but the navigation.* options I tried didn't seem to affect it.)

[squidfunk]

I'm afraid, I'm a little tight on time right now, but I invite you to ask for support on our discussion board. Our awesome community is happy to help you ☺️ As mentioned in our documentation, the discussion board is the place to get help.