[title sub="Written by Chris Graham"]Composr Supplementary: Making supplementary tutorials for Composr[/title]

[box="Potentially Outdated Tutorial"]This supplementary tutorial might be outdated as it was written for a previous version of Composr CMS (version 10).[/box]

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, [url="but GitLab has a tutorial"]https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html[/url].

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 composr.app website. We prefer to have things in Git so they stay online, and stay updated, but something is always better than nothing.

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

[title="2"]Adding your tutorial[/title]

[list="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.

[*] You'll find the tutorials are all written as Comcode pages in [tt]docs/pages/comcode_custom/EN[/tt].

[*] 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 [tt]sup_whatever.txt[/tt]. We strictly use only lower case characters, and underscores rather than spaces.

[*] If you have images, they'll be in a new directory you create [tt]data_custom/images/docs/<TUTORIAL_BASE_FILENAME>[/tt]. E.g. [tt]data_custom/images/docs/sup_whatever[/tt].

[*] 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="Comcode"]
[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]
[/code]

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 [tt][surround][/tt] 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 [tt]themes/default/images/icons/spare[/tt] to find the icons. The tag names are capitalised, while the icon filenames are lower case using underscores. It's quite intuitive: [tt]feedback_features.png[/tt] is for tag [tt]Feedback Features[/tt]. Ampersands have special handling: [tt]advice_and_guidance[/tt] is for tag [tt]Advice & Guidance[/tt].
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 [tt]downloads[/tt] addon, reference that.
If you do reference an addon, you must also make the reference from the [tt]addon_registry[/tt] file to your tutorial. Edit the [tt]sources_custom/hooks/systems/addon_registry/<ADDON>.php[/tt] file so that the [tt]get_applicable_tutorials()[/tt] 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 [tt]novice[/tt], [tt]regular[/tt], or [tt]expert[/tt].

[*] Preview your tutorial from [tt]http://yourbaseurl/docs/index.php?page=<TUTORIAL_BASE_FILENAME>[/tt].

[*] As tutorials are a part of the non-bundled [tt]composr_tutorials[/tt] addon, all your new files must be referenced from the [tt]get_file_list()[/tt] function of [tt]sources_custom/hooks/systems/addon_registry/composr_tutorials.php[/tt].

[*] We also have some automated tests for testing the tutorials all stay consistent. To run these go to [tt]http://yourbaseurl/_tests[/tt] and run all the tests starting [tt]tutorial[/tt]. Make sure they pass. Also running the [tt]modularisation[/tt] test is a good idea, to make sure you have updated the [tt]addon_registry[/tt] file correctly, and haven't left unreferenced files.

[*] Add/Commit/Push your work (standard Git workflow).

[*] 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.
[/list]

{$SET,tutorial_tags,Advice & Guidance,expert,Contributing}{$SET,tutorial_add_date,Nov 2015}{$SET,tutorial_summary,This tutorial will show you how to add a new supplementary tutorial to Composr.}[block]main_tutorial_rating[/block]
