This issue proposes that help files be optionally processed using input filters. This will enable help files to be written in alternative formats like Markdown or Textile, as well as open the doors to support more expressive features such as syntax highlighting or easily embed external videos using simplified syntax.
This feature can be used by specifying a list of input filters in the .ini file:
[example-code]
title = Example Code
input filters[] = filter_markdown
input filters[] = geshifilter
extension = md
Extensions can also be specified, instead of hard-coding the ".html" extension.
The forthcoming patch is a first-pass at implementing this feature. I would consider it as "needs work" since it presents a new problems to consider:
- What happens when the requested input filter is unavailable to the site? Should we display a notice that the document is "best viewed" with said filters?
- How do we handle filters that ARE available, however, require external libraries or API key configurations before they can work properly.
- How can we specify hard requirements for input filters without burdening the developer? Certain documents can appear like gibberish if not processed through the appropriate filter (such as Textile), while others only provide complimentary formatting (such as syntax highlighting)
- How can we leverage this feature to README files that are written in markdown or textile, without hard-coding assumptions based on file extension?
- Core's Filter module has a poor API that tightly binds itself to formatter objects that are saved to the database. Currently, the patch provides alternative API functions that bypass the use of formatters and uses the input filters directly.
Despite these issues, this is a working patch and has been tested against some of the more popular input filters in contrib. I'm posting this patch to reference in my own make files, and so hopefully others can discuss/improve upon it.
| Comment | File | Size | Author |
|---|---|---|---|
| #2 | filters-1649588-2.patch | 10.97 KB | helior |
| #1 | filters-1649588-1.patch | 10.96 KB | helior |
Comments
Comment #1
helior commentedComment #2
helior commentedPrevious patch won't apply because of an extremely small whitespace change. Go figure.
Comment #3
gisleI am going to add support for the markdown filter module, but will use the patch in #1405734: Output READMEs as parsed Markdown instead of this one.