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

Before submitting a hint, check if there is an already existing hint on the topic. If
there is then contact the author if you have any updates. If the previous author is not
interested in maintaining the hint, or if there is no response from the author for at
least a month, then you may take over maintenance of the hint. Remember to CC hints-owner@linuxfromscratch.org
regarding all correspondence with the author so that the hint maintainers are
aware of the changeover.Note that this does not mean that duplicate hints on the same topic are not allowed.
If you feel that the current author has a different approach to a problem and you have
one which does not match the current hint, feel free to submit a separate hint. We suggest
communicating with the current author(s) before writing the hint. We suggest writing a
short blurb on how the new hint differs from the existing one.

Hints should be reserved for things that cannot be included into the book. Hints that
relate to installation of packages and which would easily fit into the book (usually the
BLFS book) should be submitted to the relevant development list. If you are conversant
with docbook and XML, then feel free to submit a patch to the current CVS Book version.
If not, submit a text file matching the current format of the book and a book editor will
do the necessary modifications.

If you are in the process of writing a hint on a topic, it would be good to drop a line
to the relevant list in case someone else is working on something similar.

A hint should not duplicate documentation that is already available elsewhere on a
particular topic, it should complement it. Documentation available elsewhere includes
LDP documentation,
documentation available from the package website, documentation available
by a simple
google search. Also, things that are already well
documented in the book(s) or
at the LDP should not be repeated in the hint unless the hint describes matters in more
detail, in a different way, or from a different perspective. So things such as installation
of db, freetype, zlib, etc can just be referenced by pointers to the book.

Authors who are not interested in maintaining their hints any more should send a message
to the hints mailing list specifying that the hint is
up for adoption. The author should
also notify the hints list if the hint is not relevant anymore.

Hints that have been integrated into the book will be retired after a stable version of
the book is released.

Keep the file name of the hint short, but descriptive. The extension for the hint should be
.txt. The name may be composed of a combination of lowercase letters, numbers, and a few
symbols _ - +.

The hint document is text based. The format for the hints is as explained at the end of
this document.

Avoid including scripts and patches in the hints. Keep these as separate files to avoid
spoiling the beauty of the hint. :) Patches should follow the
patches format. The patches
that you submit will be committed to the patches repository (so be sure to mention the hint
in the patch description) under the appropriate package name. The scripts or patches that
don't fit into the patches project will be available from the
Attachments link on the
download page.
If you need to reference any patches in your hint, point to the patches subproject
(e.g. http://www.linuxfromscratch.org/patches/<package_name>/<patch_name>). If
you need to reference to any attachments, point to the attachments directory
(e.g. http://www.linuxfromscratch.org/hints/downloads/attachments/<hint_name>/) Don't
worry if the URIs are incorrect, the maintainer will modify the URIs before submitting.
Since maintainers are sometimes lazy, you may need to give them a bit of a push/shove to
"do the right thing".

To submit or update a hint, send an e-mail to the
hint mailing list. From there
it will be picked up by the hint maintainer, who will update the hint index and the tarball.
To check if your hint has already been included, you can
subscribe to the hints mailing list
and check for the CVS commit message. Keep the hints list solely for submitting hints and
updates to hints.

Note that by submitting a hint, you agree to the conditions mentioned on this page with respect
to the hint. In particular, you allow other users to take over the maintainership of the hint if
another user contacts you with a request (for taking over the maintainership or integrating
his/her work in your hint) and you fail to respond to the request for a month. If you would not
like someone to take over the maintainership of the hint, please state so clearly in the hint.
Authors should also keep the contact information updated.

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:

[YYYY-MM-DD]

* Changed A

* Changed B

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.