Martin Atkins (mart) wrote in lj_userdoc,
Martin Atkins
mart
lj_userdoc

Rich FAQs

rahaeli requested that FAQs support some form of markup to make them more readable. This is something that has bothered me for a while, so I worked on it yesterday and my patch is currently sitting in Zilla (LJ Bugtracker) awaiting review, testing and application.

In the mean time, though, I thought I'd post about it to describe the changes and what they can do. I suppose a good place to start is the tag reference. The new Rich FAQ system uses HTML-like markup, but it isn't actually HTML. Instead, it's a simpler language which contains a small set of meaningful tags. It's my hope that by only supporting meaningful tags, rather than directly stylistic tags, the FAQs will start to be more consistant and can also relate better to the global site template. It also means that I can include some extra things useful for FAQs in particular.

  • <p> - Paragraph
  • <h> - Heading
  • <ol> - Ordered List (instructions, etc)
  • <ul> - Unordered List (a list where order is irrelevant)
  • <li> - A list item inside either <ol> or <ul>
  • <code> - Block-level (multi-line) code
  • <icode> - Inline code (short references to HTML tags, Style identifiers, etc)
  • <em> - Add Emphasis
  • <a href="..."> - Create a regular link to the given URL
  • <a faqref="x"> - Create a link to FAQ entry number x
  • <a faqref="cat:category"> - Create a link to the given FAQ category
  • <lj user="someone"> - Create a link to normal user 'someone'
  • <lj comm="suggestions"> - Create a link to the community 'suggestions'
  • <escape> - All HTML inside this tag will be escaped and auto-formatting will be done

This seems to cater for all current FAQ requirements. The two code tags automatically HTML escape their contents so that it's easy to include style override examples, HTML and so forth. Inline code is more intended for refering to things in the flow of a sentence, such as “To add to the <icode><head></icode> section of all pages, use the <icode>GLOBAL_HEAD</icode> variable.”

The system is quite strict about valid markup, because it translates a lot of markup into other forms such as BML, so it has to be well-formed. Also, enforcing structure goes further to making the FAQs consistant with each other.

FAQs are assumed to be old-style, text-only FAQs until a paragraph or heading is encountered, so all rich FAQs must begin with a paragraph or a heading. They should anyway, so I didn't think this was a bad restriction. Suddenly changing all of the FAQs will cause a nightmare for the translation teams, so it's probably better to just leave the FAQs which are pretty simple texty stuff until they need to be changed, at which point the markup can be added. Adding markup won't require much change to the FAQs, although any place that references a link will need to be reworded so that it doesn't say “Look at this page: [URL]” but instead “Look at your User Information page”.

I don't know how long it'll be before my code goes on the site, but since it's quite a big patch Brad'll probably want it reviewed by a couple of people before he accepts it. In the mean time, there's some warning for you all! ;) You'll know when this is available because the above tag reference will appear on the editing page.

Subscribe
  • Post a new comment

    Error

    Comments allowed for members only

    Anonymous comments are disabled in this journal

    default userpic

    Your reply will be screened

    Your IP address will be recorded 

  • 9 comments