Skip to content

Contributing

Jump to bottom Edit New page
tajmone edited this page Mar 2, 2019 · 10 revisions

Help us make the Highlight project grow!

Table of Contents

Contribution 4Ws

Contributing: Who? Why? Where? and What?

Who Can Contribute?

If you're a regular and dedicated Highlight user then you can certainly contribute to the project in different ways.

For example, you could submit new contents to this Wiki. Chances are that if you're using Hihglight is because you work with one or more programming languages or markup syntaxes; you could help maintaining the syntax definitions of these languages up to date, improve them, or help us with the Highlight test suite or with the code examples collection.

You don't need to be a programmer to help with the project, there are many areas in which you could helpful.

Why Should I Contribute?

Highlight is an open source tool enjoyed by a huge number of users, and steadily growing through the efforts of contributors from the open source community.

Your contribution is precious to the community, and it's your change to give back to this wonderful tool that has been freely providing code beauty since 2002.

Where Can I Contribute?

You could help the project in any of these areas:

Documentation

Documentation plays an important role in the final experience of any tool. You could help this Wiki group by creating new pages and improving the current contents.

Internationalization

Internationalization and localization (i18n) play a crucial role in the spread of open source software across boundries, for the lack of documentation and user interface translations to a given language can be a huge barrier for many users.

If you're native language is other than English, you might consider helping with translations via one of the following ...

Highlight GUI i18n

You could help with the translation of Highlight GUI user interface. Highlight GUI use Qt 5, so you'll need the Qt Linguist tool (which is part of the Qt distribution) to edit the *.ts files inside Highlight src/gui-qt/ folder:

For more information, see:

Wiki i18n

You could fork the upstream Highlight repository and start a new Highlight Wiki in your native language, or any other language you're fluent with. You have total freedom to translate, reuse and otherwise adapt the contents of this Wiki.

Syntaxes

Over the years different people contributed new syntax definitions to Highlight, which now supports over 224 languages and markup syntaxes. Some syntaxes could be improved, others might need to be updated to reflect the current status of a given language, and some languages don't have a syntax yet.

If you're fluent in a given programming language or markup syntax, you might consider contributing by:

  • Updating current syntaxes
  • Adding new syntaxes

This Wiki provides useful information on how work with Hihglight syntax definitions, so it should be a good starting point. Creating syntaxes is not as difficoult as it might sound, but it requires knowledge of the language being defined.

For the same reason, the project is always in need of people willing to take on maintainance of specific language definitions by people who master that language. If you are commmited to a specific language, you could consider becoming the maintainer of its Highlight langDef.

Furthermore, we're also trying to create a collection of code examples for all the languages supported by Highlight, as well as a test suite to help with syntaxes maintainance.

Code Examples Collection

You can find the examples colletion in the extras/langs-examples/ folder of Highlight:

The goal of the project is to provide a source code example for every language natively supported by Highlight, so that end users can test how themes are rendered which language, as well as being able to check how well each langDef highlights the code.

Building examples that are elegant, syntax rich and meaningful at the same time is not an easy task, and defintely on that require knowldege of tha language or markup syntax. So this is an area where contributions are much needed and appreciated.

You'll find more details about the examples project in the README file inside its folder.

Highlight Test Suite

The test suite is a recent project that followed the new syntax testing feature introduced in Highlight v3.45:

The goal of the project is to create a collection of tests for all the languages supported by Highlight, in order to:

  1. Uncover and annotate edge cases that are not handled correctly by a landDef.
  2. Detected breaking changes while editing a landDef.
  3. Test a langDef against new features of a language when the latter is updated.

Developers can also use this project to test syntax developement in local branches before submitting new/updated langDefs to Highlight repository. This offers a convenient work approach, especially for language definitions which fail some tests and need updating, where the developer can run the existing test files against his/her tweaked langDef (using the --config-file= option inside a customized test script).

The idea behind the project is that by sharing with community the syntax tests created while working on our langDefs, we'll make it easier for other users to take the work from where we left it. The test suite is also useful to point out missing features in language definitions, and adding tests to show weaknesses ina langDef acts as reminder of things to be done.

What Could I Contribute?

For a start, the least you can do is show your appreciation by starring on GitLab and GitHub the Highlight project, this Wiki and related projects, thus helping them gain visibility and status:

You can also help the project with your feedback, by opening an Issue to report bugs, features requests, and other constructive suggestions.

Highlight tools

Inside Highlight extras/ folder you can find a wide range of useful assets to integrate Highlight in third party tools, aid in development, and other useful stuff:

If you've created some Highlight scripts, templates, or other useful assets which you'd like to share with the community, why not make a pull/merge request and add them to that folder?

Wiki Editing Guidelines

This Wiki is public and open to contributions, you can edit pages and create new ones directly from your browser.

It's Free as In WTFPL

By contributing contents to this Wiki you understand and implicitly accept that others might reuse these contents in other projects without restrictions.

I've willingly avoided to attach any license and strings to these contents because of the intricacy of licenses relating to documentation. I'd rather openly state that people you should free to reuses these contents as they deem fit. The purpose of the Wiki is to spread knowledge on Highlight and its usage, and whoever is doing so is helping this project too.

Being a project open to users' contributions, where pages are intended to be edited over again by different people, there is not point in claiming any authorship either, except when quoting others.

The philosophy behind this Wiki is very well summarized at this link:

you should visit the above link before contributing to the Wiki.

If you are not at ease with the idea that your contributed contents will not carry your authorship, or that they might be reused and edited by others, without them asking your permission and/or crediting you for them, then this Wiki might not be the right thing for you, and you should consider starting a documentation project of your own, using a license that safeguards your work as you see it fit.

Keep It Markdown

GitHub projects' Wiki can host pages in a variety of markup syntaxes. For the sake of consistency an easier maintainance, I would like all pages in this Wiki to be in GitHub flavoured markdown (aka "GFM"), which is a very popular markdown variant as well as GitHub's native markup syntax.

If you're more confortable writing in other markup syntaxes, you could use pandoc to convert from your favourite markup syntax to GFM:

Mind the TOC

You might have notice that most pages in this Wiki have a Table of Contents. When looking at a page's source, you might notice that the TOC is enclosed in HTML comments:

**Table of Contents**

<!-- MarkdownTOC autolink="true" bracket="round" autoanchor="false" lowercase="only_ascii" uri_encoding="true" levels="1,2,3" -->

- [Introduction](#introduction)

<!-- /MarkdownTOC -->

These HTML comment tags are used by a Sublime Text 3 plugin, called MarkdownTOC, to automagically generated a GitHub compliant Table of Content when saving the document.

So, please don't touch the TOC's comments tags. If you don't have Sublime Text, don't worry aobut the TOC contents: when I'll see that a page was changed I'll take car of updating its TOC. Any manual changes to the TOC will be overwritten and lost every time MarkdownTOC regenerates a new TOC from scratch.

Auto-Generated Pages

For maintainance conveniency, some Wiki pages are auto-generated by Bash scripts via heredoc and direct queries to Highlight command line tool:

Wiki page Generating script
CLI-Help highlight-help2md.sh
Languages-List highlight-langs2md.sh

You should not edit those pages directly, as all changes would be lost when they are updated by their scripts. If you want to improve their contents, edit their generator script heredoc template instead.

EOL NOTE — All script-generated pages must use Unix style LF EOL, whereas normally markdown files are set to native EOL in .giattributes. The reason for this is to allow running the scripts under Bash for Windows, where Highlight CLI output redirection will introduce CRLF EOLs in the generated document, along with LF EOLs generated by the script, thus preventing Git from commiting it.

To enforce LF EOL, All page-generating scripts invoke the dos2unix command on the output file after generating it. The Wiki .giattributes contains exceptions rules targetting the auto-generated files, to enforce Unix EOL on them.

All contributions are welcome and apreciated.

Tristano Ajmone

HELP US MAKE THIS DOCUMENTATION GROW BY CONTRIBUTING CONTENTS

Add a custom sidebar
Clone this wiki locally