Skip to content

OMPIFAQEntries

Jump to bottom
Jeff Squyres edited this page Jun 16, 2020 · 10 revisions

The Open MPI FAQ is a PHP-based set of scripts that uses a Github-like mini-wiki markup for creating its HTML. It was written long before we ever used Github and does not support anywhere close to the full Github/Markdown wiki markup. It only supports a few common markup entities for common actions within a FAQ entry. Other, more precise markup can be written directly in HTML (i.e., you can mix HTML and the markup in a single FAQ entry).

There are two ways of contributing FAQ content:

  1. Post a pull request against the open-mpi/ompi-www Git repo
  2. Get push permissions to the open-mpi/ompi-www repo and push them yourself

Web site implementation

The Open MPI web site is maintained in the "ompi-www" Git repository (https://github.com/open-mpi/ompi-www/). (Normal Git conventions apply. The "live" site is maintained in the master branch) For example, to check out the entire web site, use:

# This clone won't be able to push back up to Github
$ git clone https://github.com/open-mpi/ompi-www.git

# This clone will be able to push back up to Github
$ git clone [email protected]:open-mpi/ompi-www.git

The FAQ is in the faq/ subdirectory.

The top-level file is faq/index.php. There are multiple faq/*.inc files, each one corresponding to a single category. The *.inc files are read in by index.php when a category is displayed. Each *.inc file contains all the questions, anchors, and answers for that category. The index.php file contains a small engine to print out all the questions in a category and to the markup -> HTML conversion when displaying them.

WARNING: Test your PHP / FAQ changes often while editing and certainly before pushing back up to Github. The main Open MPI web site and all of its mirrors run "git pull" at unpredictable times. If you commit something broken, it may become live on a mirror web site for 24 hours before they run "git pull" again to get your fixes. To test, direct your browser to the top faq/ URL.

Once you have pushed your changes back up to Github, your changes will become live on the main Open MPI web site within an hour or so (i.e., there's a cron job that runs "git pull" at least every hour). The mirrors update at their own schedule, but will update at least once a day.

Guidelines for text

These important guidelines should be remembered when writing a FAQ entry:

  1. Use proper English grammar and spelling in the FAQ entry.
  2. Use proper punctuation; FAQ entries are not instant messages!
  3. Avoid slang and colloquialisms. We live in a global software environment; not everyone is a native-English speaker.
  4. Remember that your audience is seeking information. The answer to the question may be obvious to you, but it isn't to them. So be clear. Be explicit. Assume as little as possible.
  5. Remember that your text will shortly become Google-able, and likely be cached in many places around the globe. When writing your FAQ question, think about what a common user would want to search/google for in order to find the answer.
  6. If Open MPI displays specific error or warning messages, include that text in the FAQ entry somewhere (e.g., in a geshi section in the answer). Many users will cut-n-paste OMPI output into a google text box when looking for solutions to their problems. Putting the exact text on the FAQ page makes the answer Google-able/findable.

Adding a new category

Essentially, edit the faq/categories.inc file, mimicking the syntax you see there.

Adding a new FAQ entry

Go to the faq/*.inc file for the appropriate category. Again, mimic the structure and syntax you see there. Specifically, add three new entries:

  1. $q[] with the text of the question
  2. $anchor[] with an HTML anchor for use within this category (*.inc file or web page)
  3. $a[] with the text of the answer

Markup

Again, there is limited markup, but you can embed HTML for richer presentation. In any case, the rest of this page discusses various aspects of this markup.

Quotes

If you include quotes (") in your question or answer, you must escape them! Remember that these are PHP strings, so an un-escaped quote will terminate the string. For example:

# This is bad and will cause a run-time PHP error
# (note the syntax highlighting below shows the error)
$q[] = "When did Socrates ask, "I drank what?"";

$anchor[] = "mpirun-out-of-memory";

# This is good; the quotes will display properly in the output page
$a[] = "Socrates never said \"I drank what?\".  It is a line from the cult movie _Real Genius_.";

Boldface / asterisk

Asterisk (*): Putting asterisks around one or more words results in boldfacing those words in the output (<strong> and </strong>). For example:

The *quick brown fox* jumped over the lazy dog.

will result in output like this: The quick brown fox jumped over the lazy dog.

Note that the markup is fairly simplistic: the tokens generally need to be delimited by whitespace. For example:

The qu*ick brown f*ox jumped over the lazy dog.

Will result in "quick brown fox" being output without any HTML markup. If you need sophisticated HTML in the middle of words, use HTML directly. For example:

The qu<strong>ick brown f</strong>ox jumped over the lazy dog.

This limitation applies to other markup such as underscores and square brackets as well.

Emphasis / underscore

Underscore (_): Putting underscores around one or more words results in emphasizing those words in the output (<em> and </em>). For example:

The _quick brown fox_ jumped over the lazy dog.

will result in output like this: The quick brown fox jumped over the lazy dog.

Fixed font / square brackets

Putting square brackets ([]) around one or more words results in using a fixed font (<code> and </code>). For example:

The [quick brown fox] jumped over the lazy dog.

will result in output like this: The quick brown fox jumped over the lazy dog.

Long sections of fixed-width text

To display some code or perhaps an example text file, use the <geshi LANGUAGE> and </geshi> delimiters. The LANGUAGE token tells the Geshi syntax highlighting engine what conventions to use to make the rendered text look pretty. Common values for LANGUAGE are:

  • bash: shell scripting
  • c: C source code
  • text: plain text -- no highlighting (but still add line numbers)
  • make: Makefiles
  • python: Python
  • ini: INI-style files

The FAQ engine will convert this to a <code>-based environment, but also set the background and an enclosing text box (similar to what Github does for multi-line 3-single-quote sections), add line numbers, and add syntax highlighting.

Meaning: avoid <code> and </code> directly -- use <geshi LANGUAGE> and </geshi>.

Linking to on-site URLs

It's a best practice when linking to other pages in the Open MPI web site to use relative links. I.e., link to $topdir/about/members/ instead of http://www.open-mpi.org/about/members/, where $topdir is a pre-defined PHP variable that will either be ".", or "..", or "../..", or whatever is relevant to reach the top-level directory relative to where the current page is located.

This helps keep all in-the-tree links actually in the tree, and ensures that if you git clone ... the ompi-www repository in a non-docroot folder, you can still view/test/debug your code properly.

Clone this wiki locally