Modding Tutorial Book (new: Code architecture, unit testing)

User avatar
rubenwardy
Moderator
Posts: 6273
Joined: Tue Jun 12, 2012 18:11
GitHub: rubenwardy
IRC: rubenwardy
In-game: rubenwardy
Location: United Kingdom
Contact:

Modding Tutorial Book (new: Code architecture, unit testing)

by rubenwardy » Post

This online book will (eventually be able to) teach you how to create mods in easy chapters. The chapters will explain a concept, give examples, and set tasks for you to complete.

This documentation was created by the Minetest community in order to help new modders gain a foothold.

Work in progress. I'd like suggestions for contents. What chapters would you like to see?

Read it online - Download

Contribute on GitHub, or by sending me documents for new chapters.
(I'll format them and add them, the content is the hardest thing, not the formatting.)

Done
  • Folder structure
  • Lua Scripts
  • Nodes, Items and Crafting
  • Creating textures
  • Node Drawtypes
  • Node Metadata
  • Active Block Modifiers
  • Chat and Commands
  • Player Physics
  • Formspecs
  • HUD
  • ItemStacks
  • Inventories
  • Releasing a Mod
  • Read More
Todo
(please feel free to work on any of these, or any other chapter you want to do)
  • Entities
  • Particles
  • Sound
  • Mapgen and LVM
  • Organising code - patterns
  • ...
Last edited by rubenwardy on Fri Apr 15, 2016 23:14, edited 32 times in total.

User avatar
ExeterDad
Member
Posts: 1717
Joined: Sun Jun 01, 2014 20:00
In-game: ExeterDad
Location: New Hampshire U.S.A

Re: Minetest Tutorial Book - Creating Better Documentation

by ExeterDad » Post

You are to be worshipped from this day forward.

User avatar
philipbenr
Member
Posts: 1688
Joined: Fri Jun 14, 2013 01:56
GitHub: philipbenr
IRC: philipbenr
In-game: robinspi
Location: United States

Re: Minetest Tutorial Book - Creating Better Documentation

by philipbenr » Post

Hmmm. I think that I might just do one with pure html and css. It would be nicer and easier for most people to make.

User avatar
rubenwardy
Moderator
Posts: 6273
Joined: Tue Jun 12, 2012 18:11
GitHub: rubenwardy
IRC: rubenwardy
In-game: rubenwardy
Location: United Kingdom
Contact:

Re: Minetest Tutorial Book - Creating Better Documentation

by rubenwardy » Post

Philipbenr, yeah no. Markdown is easier to create, you can still get html exports. I'll start making them when I get more chapters.

Markdown is human readable, so makes sense as plain text.

You can just write chapters as a text file in chapters, and I will link and correct formatting. You never actually need to use Jekyll. Feel free to submit a word document. Writing is the hard bit, not the formatting.

Jekyll allows you to include other HTML files. Much easier.

User avatar
Evergreen
Member
Posts: 2135
Joined: Sun Jan 06, 2013 01:22
GitHub: 4Evergreen4
IRC: EvergreenTree
In-game: Evergreen
Location: A forest in the midwest
Contact:

Re: Minetest Tutorial Book - Creating Better Documentation

by Evergreen » Post

THANK YOU
Back from the dead!

leeminer
Member
Posts: 90
Joined: Mon Aug 11, 2014 21:29

Re: Minetest Tutorial Book - Creating Better Documentation

by leeminer » Post

I wish I had more thumbs.. two thumbs up!!!

User avatar
philipbenr
Member
Posts: 1688
Joined: Fri Jun 14, 2013 01:56
GitHub: philipbenr
IRC: philipbenr
In-game: robinspi
Location: United States

Re: Minetest Tutorial Book - Creating Better Documentation

by philipbenr » Post

Truthfully, I find markdown confusing and html more organized. More complex, but more organized.

Edit: Plus, with css, I can do some really amazing effects, plus make a popup of pure css(3?) (strange, huh?) It would be harder for a person to add to it, but it would be easy for some web developers. Personally, when I used markdown, it took more memorization than html. There were div (dividers) and p (paragraph) and h_ (header, size _) and the like. It is different with different versions of markdown, but I find html easier to memorize.
Last edited by philipbenr on Fri Dec 12, 2014 01:46, edited 1 time in total.

leeminer
Member
Posts: 90
Joined: Mon Aug 11, 2014 21:29

Re: Minetest Tutorial Book - Creating Better Documentation

by leeminer » Post

For those who don't know what markdown is. Like me.

http://en.wikipedia.org/wiki/Markdown

User avatar
rubenwardy
Moderator
Posts: 6273
Joined: Tue Jun 12, 2012 18:11
GitHub: rubenwardy
IRC: rubenwardy
In-game: rubenwardy
Location: United Kingdom
Contact:

Re: Minetest Tutorial Book - Creating Better Documentation

by rubenwardy » Post

Anything is confusing if you don't put any time into learning it. The tutorial is supposed to be written by authors, not web developers.

You can use HTML in markdown. Markdown isn't hard. Popups are not needed.

BTW, the HTML is in _includes/header.html and _includes/footer.html.
CSS is in static/style.css

I don't see your point.
These are really the only things you need:
(Plus images)

Code: Select all

Section
-------

Here is some text

### source code
    Code snippets are
    Tabbed one level in.

Another paragraph

* one
* two
* three

[Link](http://URL)

<b>this is perfectly valid<\b>
The tutorials should be printable, in theory

User avatar
srifqi
Member
Posts: 557
Joined: Sat Jun 28, 2014 04:31
GitHub: srifqi
IRC: srifqi
In-game: srifqi
Location: Indonesia

Re: Minetest Tutorial Book - Creating Better Documentation

by srifqi » Post

+1

I don't know which is better HTML or Markdown, for me it's same.
Saya dari Indonesia! · Terjemahkan Minetest! · my mods · My nickname in IPA: /es.rif.qi/

User avatar
Linuxdirk
Member
Posts: 2627
Joined: Wed Sep 17, 2014 11:21
In-game: Linuxdirk
Location: Germany
Contact:

Re: Minetest Tutorial Book - Creating Better Documentation

by Linuxdirk » Post

rubenwardy wrote:Markdown isn't hard.
Markdown is easy as pie :D
srifqi wrote:I don't know which is better HTML or Markdown, for me it's same.
For content … Markdown is better.

User avatar
philipbenr
Member
Posts: 1688
Joined: Fri Jun 14, 2013 01:56
GitHub: philipbenr
IRC: philipbenr
In-game: robinspi
Location: United States

Re: Minetest Tutorial Book - Creating Better Documentation

by philipbenr » Post

Okay, I just want to say, I do see your point, but this is what I was talking about when I said you can do cool stuff. There is no javascript involved in this whatsoever. You can hover on the quote slider to stop it, and you can hover on the cards to make them zoom, (Also, sorry about the cards. I was lazy, so I just did a quick fix and put them in a table. I should just change a couple things around and fix that to be normal for all zooms and displays. Same with the height of the quote slider. But still. There is a lot of cool stuff in there, isn't there?)
Attachments
Minetest.zip
This is a single html page and single css stylesheet modeled after the homepage. It should work in almost all browsers, but maybe not IE 9 (That one has had compatibility issues in general)
(785.92 KiB) Downloaded 96 times
“I'd far rather be happy than right any day.”

User avatar
rubenwardy
Moderator
Posts: 6273
Joined: Tue Jun 12, 2012 18:11
GitHub: rubenwardy
IRC: rubenwardy
In-game: rubenwardy
Location: United Kingdom
Contact:

Re: Minetest Tutorial Book - Creating better Documentation

by rubenwardy » Post

1) you can do that with my markdown thing. CSS can be used, so can HTML.
2) it's not needed for this project.

I do like CSS, although it is a pain when doing columns or mixing fixed and %.

leeminer
Member
Posts: 90
Joined: Mon Aug 11, 2014 21:29

Re: Minetest Tutorial Book - Creating Better Documentation

by leeminer » Post

To tell you all the truth, if you told me the tutorial Rubenwardy made was a text file without HTML markup I would have thought you were crazy.

The point of a tutorial isn't fancy CSS or HTML or javascript, the point is to show examples, and tutor people with info. I find the format and style super easy to read. We should focus on the content I say.

Rubenwardy, let us know what we can do. Like I suggested before, maybe we start an FAQ and add that to your documentation some how?

What does everyone think of an FAQ idea. For a noob to minetest like me, a FAQ would be greatly helpful, and in conjunction with the tutorial really great.

Maybe even a FAQ for each chapter?

User avatar
rubenwardy
Moderator
Posts: 6273
Joined: Tue Jun 12, 2012 18:11
GitHub: rubenwardy
IRC: rubenwardy
In-game: rubenwardy
Location: United Kingdom
Contact:

Re: Minetest Tutorial Book - Creating Better Documentation

by rubenwardy » Post

I would like to add 'tip' and 'watch out' boxes. This online book will be in the similar style to a teach teach yourself in 24 hours style book. FAQs will be talked about in the paragraphs.

I would like a list of possible chapters, and suggestions on what common mistakes and problems are.

User avatar
Evergreen
Member
Posts: 2135
Joined: Sun Jan 06, 2013 01:22
GitHub: 4Evergreen4
IRC: EvergreenTree
In-game: Evergreen
Location: A forest in the midwest
Contact:

Re: Minetest Tutorial Book - Creating Better Documentation

by Evergreen » Post

I found a really great intro to vimscript that we could take some inspiration from. (it uses markdown for its formatting)
http://learnvimscriptthehardway.stevelosh.com/
And no, this was not written by Zed Shaw. In fact, I think it is way better than learn python the hard way.
Back from the dead!

leeminer
Member
Posts: 90
Joined: Mon Aug 11, 2014 21:29

Re: Minetest Tutorial Book - Creating Better Documentation

by leeminer » Post

Evergreen wrote:I found a really great intro to vimscript that we could take some inspiration from. (it uses markdown for its formatting)
http://learnvimscriptthehardway.stevelosh.com/
And no, this was not written by Zed Shaw. In fact, I think it is way better than learn python the hard way.

Visually its kind of blah.. Trying to define blah, not much color or variation or anything to draw your eyes to where they should go.. if that makes sense.

User avatar
Evergreen
Member
Posts: 2135
Joined: Sun Jan 06, 2013 01:22
GitHub: 4Evergreen4
IRC: EvergreenTree
In-game: Evergreen
Location: A forest in the midwest
Contact:

Re: Minetest Tutorial Book - Creating Better Documentation

by Evergreen » Post

leeminer wrote:
Evergreen wrote:I found a really great intro to vimscript that we could take some inspiration from. (it uses markdown for its formatting)
http://learnvimscriptthehardway.stevelosh.com/
And no, this was not written by Zed Shaw. In fact, I think it is way better than learn python the hard way.

Visually its kind of blah.. Trying to define blah, not much color or variation or anything to draw your eyes to where they should go.. if that makes sense.
I'm not giving it as an example for color, I'm giving it as an example for content.
Back from the dead!

User avatar
rubenwardy
Moderator
Posts: 6273
Joined: Tue Jun 12, 2012 18:11
GitHub: rubenwardy
IRC: rubenwardy
In-game: rubenwardy
Location: United Kingdom
Contact:

Re: Minetest Tutorial Book - Creating Better Documentation

by rubenwardy » Post

Added a chapter on registering nodes, craftitems and crafting. Next I will be doing formspecs.

You can download a zip of the website here: https://github.com/rubenwardy/minetest_doc/releases

User avatar
Evergreen
Member
Posts: 2135
Joined: Sun Jan 06, 2013 01:22
GitHub: 4Evergreen4
IRC: EvergreenTree
In-game: Evergreen
Location: A forest in the midwest
Contact:

Re: Minetest Tutorial Book - Creating Better Documentation

by Evergreen » Post

By the way, here is where you can contribute: https://github.com/rubenwardy/minetest_doc
Back from the dead!

leeminer
Member
Posts: 90
Joined: Mon Aug 11, 2014 21:29

Re: Minetest Tutorial Book - Creating Better Documentation

by leeminer » Post

Rubenwardy,.. perhaps add a link in your signature to the Tutorial. Would make it easy for us to review it... I'll check the update and give some feedback when able today.

Thanks man..

User avatar
Don
Member
Posts: 1643
Joined: Sat May 17, 2014 18:40
GitHub: DonBatman
IRC: Batman
In-game: Batman

Re: Minetest Tutorial Book - Creating Better Documentation

by Don » Post

I am looking forward to the formspec chapter. I have put my millwork mod on hold until I figure out how to make a couple machines for it.

One thing that I have trouble with is knowing where to put things. I am not a programmer. In some mods there is code before the node definition and in others it is in the node definition. A chapter on the code structure would be nice.
I learned a little about ipairs and tables. I haven't found much info on how to use them. I am learning from other peoples mods. I would love to learn more about them.
Thank you for doing this book. I means a lot to me and I am sure many other people.
Many of my mods are now a part of Minetest-mods. A place where you know they are maintained!

A list of my mods can be found here

Zeno
Member
Posts: 140
Joined: Sun Jun 29, 2014 03:36
GitHub: Zeno-
Location: Australia

Re: Minetest Tutorial Book - Creating Better Documentation

by Zeno » Post

I'd prefer LaTex before HTML/CSS. Markdown is easy and it's probably easier to get others to help if it's easy to do.

User avatar
rubenwardy
Moderator
Posts: 6273
Joined: Tue Jun 12, 2012 18:11
GitHub: rubenwardy
IRC: rubenwardy
In-game: rubenwardy
Location: United Kingdom
Contact:

Re: Minetest Tutorial Book - Creating Better Documentation

by rubenwardy » Post

Hi Don. The formspec chapter will be the next I write - you should expect it in the next 48 hours. I will write a chapter on code organisation. It is a great idea.

User avatar
Linuxdirk
Member
Posts: 2627
Joined: Wed Sep 17, 2014 11:21
In-game: Linuxdirk
Location: Germany
Contact:

Re: Minetest Tutorial Book - Creating Better Documentation

by Linuxdirk » Post

Zeno wrote:I'd prefer LaTex before HTML/CSS.
LaTeX is awesome in it’s field of work but rather not in the web publishing section :) I’d prefer LaTeX over anything else when I want to create text I want to print or publish in PDF form.
Zeno wrote:Markdown is easy and it's probably easier to get others to help if it's easy to do.
Markdown is more or less “natural writing”. You have little to no syntax elements for parsing except the ones you need to add anyways to structure the context itself (lists, headings, etc.).

Post Reply

Who is online

Users browsing this forum: Google [Bot] and 0 guests