Hint Submission

How to write a hint

A good hint provides information which is not otherwise easily obtainable. In general, we're not interested in hints which copy information already in LFS or BLFS or hints which simply list the steps needed for installing a package as explained in the INSTALL or README of a package.

This still leaves a broad scope of subjects. Hints can be about anything for which a non-obvious or non-trivial fix or hack is required. A hint can also explain a complicated package installation or a particular setup. Have a look at some other hints to get an idea of what a hint may include. Also check out the Adopt a hint program in case there is some cute little hint that you would like to nurture or if someone has suggested a topic for a hint that you have knowledge about.

Once you have a good idea for a hint, you can start writing. Stick to the following style rules if you want to submit it for inclusion.

Submission guidelines

Hint Format

Every hint should have the following sections, in the order specified here so as to have a consistent look and feel. Sections that are supposed to be single lines should be on the same line as the section header. Sections that are more than one line should begin from the line following the header. Check out the example hint to get an idea about the format.

Hint authors may be interested in a rudimentary script that checks the format of the hint. If the script reports an error, there is a huge possibility that the hint will be returned to you for reformatting. Suggestions to make the script more feature rich are always welcome.

AUTHOR:

This field can be repeated if there are multiple authors. Each author line should have name and contact details of the hint author. Restrict this field for the current authors of the hint. Previous authors should be acknowledged in the ACKNOWLEDGEMENTS section.

DATE:

The date the hint was last updated in international format (YYYY-MM-DD).

LICENSE:

The license under which the hint is licensed. The hint maintainers suggest GNU Free Documentation License, but you are free to choose your own. The GNU Free Documentation License allows copying of your hint and modifying it without restriction, with the exception that you will always be credited as author. It also indicates that the hint carries no guarantees. For more information on various licenses, visit the GNU website. Before submitting the hint, verify that a copy of the LICENSE under which your hint is licensed is available in the LICENSES directory. If not, at the time of submission of the hint, also include a note and a URI for the hint maintainer to download a text copy of the LICENSE.

SYNOPSIS:

A one line description about the hint. Please keep this short and sweet and restrict it to a single line since this is the title that would be included on the hints page.

PRIMARY URI:

This is an optional section for authors who like to host their own hints and only submit occasional updates to the official hints site.

DESCRIPTION:

A short description on why the hint was written, who is the target audience, etc. This would help a user in determining whether the hint is useful for her/him.

ATTACHMENTS:

Links to additional downloads such as patches, scripts, config files, etc. This section is optional.

PREREQUISITES:

In this section list the pre-requisites that the user needs to be aware of before following the hint. This section can be used to indicate if the hint is applicable only for a particular LFS version.

HINT:

This is the heart of the hint. List the details about your hint here. There is no restriction on how you format things in this section, except (there is always some exception) to avoid lines that look like a section (i.e. Text in all UPPERCASE followed by a semi-colon). Also, make your best effort to restrict each line to 80 columns (though this can be relaxed on case-by-case basis). Avoid including material that is already in the book.

ACKNOWLEDGEMENTS:

Acknowledgements for people who have contributed to the hint. This section is optional.

CHANGELOG:

Include timestamped changes that have occurred in the hint. Add latest entries at the end. Entries in this section should be as follows:

NOTE:

These instructions are based on responses from many users, in particular the following threads: Expired and Outdated hints and Reorganization of hints. If you have suggestions for improving this document, feel free to discuss it on the hints mailing list or drop a line to the hint maintainers at hints-owner@linuxfromscratch.org. The lfs-hints project is currently maintained by Bruce Dubbs.