Composr Supplementary: Making supplementary tutorials for Composr

This tutorial will show you how to add a new supplementary tutorial to Composr.
You will need commit access to do this, which is given out to established community members.
If you do not yet have commit access then you can submit a merge request, however. This isn't directly described in this tutorial, but GitLab has a tutorial.

Git too complex? Very understandable, in which case you can ask a developer to help you, or simply submit a link to your own hosted copy of the tutorial via the obvious spot on the compo.sr website. We prefer to have things in git so they stay online, and stay updated, but something is always better than nothing.

Adding your tutorial

1. Set up git. You'll need to pull and install Composr from the git repository, so you have a working site to write into.
2. You'll find the tutorials are all written as Comcode pages in docs/pages/comcode_custom/EN.
3. There's a concept of "supplementary" documentation. This isn't primary documentation, but rather provides additional perspectives or specific techniques. The supplementary tutorials are named sup_whatever.txt. We strictly use only lowercase characters, and underscores rather than spaces.
4. If you have images, they'll be in a new directory you create data_custom/images/docs/<TUTORIAL_BASE_FILENAME>. E.g. data_custom/images/docs/sup_whatever.
5. Create a text file in your favourite editor, and structure it similar to how existing files are structured.
   
   The basic structure is as follows:
   

   Code

   [title sub="Written by <NAME>"]Composr Supplementary: <TITLE>[/title]

[surround]
[media width="150" float="right" description="<IMAGE_DESCRIPTION>"]data_custom/images/docs/<TUTORIAL_BASE_FILENAME>/<IMAGE_FILENAME>[/media]
<INTRO>
[/surround]

[contents]decimal,lower-alpha[/contents]

[title="2"]<SOME HEADING>[/title]

<CONTENT>

{$SET,tutorial_tags,<TAGS>,<ADDON>,<DIFFICULTY_LEVEL>}{$SET,tutorial_add_date,<3_LETTER_MONTH> <YEAR>}{$SET,tutorial_summary,<SUMMARY>}[block]main_tutorial_rating[/block]

   
   Most of this is self-explanatory.
   
   You can please as many images as you like (or none), wherever you like. Often you'll want to use Comcode's [surround] tag to contain them next to paragraphs, as shown in the example.
   
   You can have as many headings as you like. If you use no headings, don't include the table of contents.
   
   The tutorial tags is a bit complex. We use a standard set of tag names matching our icon set. Look in themes/default/images_custom/tutorial_icons to find the icons. The tag names are capitalised, while the icon filenames are lower case using underscores. It's quite intuitive: feedback_features.png is for tag Feedback Features. Ampersands have special handling: advice_and_guidance is for tag Advice & Guidance.
   The first tag determines the icon used. You must use at least one tag.
   
   The addon is optional, but if your tutorial relates to a specific addon you should reference it here. For example, if it relates to the downloads addon, reference that.
   If you do reference an addon, you must also make the reference from the addon_registry file to your tutorial. Edit the sources_custom/hooks/systems/addon_registry/<ADDON>.php file so that the get_applicable_tutorials() function includes your tutorial name in the list.
   When editing any PHP file please be very careful with your formatting. We use strictly spaces instead of tabs, with 4-space indentation. Lay it out like it looks for other tutorials and you'll be golden.
   
   The difficulty level can be either novice, regular, or expert.
6. Preview your tutorial from http://yourbaseurl/docs/index.php?page=<TUTORIAL_BASE_FILENAME>.
7. As tutorials are a part of the non-bundled composr_tutorials addon, all your new files must be referenced from the get_file_list() function of sources_custom/hooks/systems/addon_registry/composr_tutorials.php.
8. We also have some automated tests for testing the tutorials all stay consistent. To run these go to http://yourbaseurl/_tests and run all the tests starting tutorial. Make sure they pass. Also running the modularisation test is a good idea, to make sure you have updated the addon_registry file correctly, and haven't left unreferenced files.
9. Add/Commit/Push your work (standard git workflow).
10. It would be good to then post on the forum to let people know of your commit (with a link to see it on GitLab), so people can appreciate and discuss your work, and collaborate.

Feedback

Have a suggestion? Report an issue on the tracker.