How to Contribute to this documentation

The documentation resides in the gh-pages branch of Carbon.

Fork Carbon
git clone
git checkout gh-pages
git checkout -b [speaking-new-branch-name]
Modify .src.html source files
git commit
git push
Create a pull request against the gh-pages branch

This documentation use commands to lint sample source codes, execute and inject the actual results of examples into a generated doc.

Don't make changes to the [a-z]+.html files directly! We'll generate those files using composer generate before releasing the documentation when releasing a new version.

Change the associated [a-z]+.src.html and then use the generate script to generate the new [a-z]+.html file. It can be run at the command line using composer generate from the project root when in the gh-pages branch. Maybe someday I'll extract this out to another project or at least run it with a post receive hook, but for now its just a local tool, deal with it.

The commands are quickly explained below. To see some examples you can view the raw docs/index.src.html file in this repo.

The lint command is meant for confirming the code is valid and will eval() the code passed into the function.c Assuming there were no errors, the executed source code will then be injected back into the text replacing out the {{::lint()}}. When you look at the raw docs/index.src.html you will see that the code can span several lines. Remember the code is executed in the context of the running script so any variables will be available for the rest of the file.

{{::lint($var = 'brian nesbitt';)}} => $var = 'brian nesbitt';

As mentioned the $var can later be echo'd and you would get 'brian nesbitt' as all of the source is executed in the same scope.

{{::exec()}} and {{eval}}

The exec command begins by performing an eval() on the code passed into the function. The executed source code will then be injected back into the text replacing out the {{varName::exec()}}. This will also create a variable named varName_eval that you can then place anywhere in the file and it will get replaced with the output of the eval(). You can use any type of output (echo, printf, var_dump etc) statement to return the result value as an output buffer is setup to capture the output. As a shortcut, you also can use simply {{::exec()}} with no varName then display the last executed result with {{eval}}.

{{::exec(echo $var;)}} => echo $var;
{{eval}} => brian nesbitt  // $var is still set from above
{{exVarName_eval}} => 2 // named eval can be display before the execution or after many other executions
{{exVarName::exec(echo 2;)}} => echo 2;
{{::exec(echo 3;)}}
{{otherName::exec(echo 4;)}}
{{exVarName_eval}} => 2 // no matter where it's positioned, it always refers to exVarName::exec result

/pad()/

The pad() is a special source modifier. This will pad the code block to the indicated number of characters using spaces. Its particularly handy for aligning // comments when showing results.

{{exVarName1::exec(echo 12345;/*pad(20)*/)}} // {{exVarName1_eval}}
{{exVarName2::exec(echo 6;/*pad(20)*/)}} // {{exVarName2_eval}}

... would generate to:

echo 12345;          // 12345
echo 6;              // 6

How to Contribute to this documentation

{{::lint()}}

{{::exec()}} and {{eval}}

/*pad()*/

/pad()/