1059685 - Add user help for Markdown

Status: RESOLVED FIXED

(Bugzilla :: Documentation, enhancement)

Description

[:glob ✱]

help within the current markdown implementation (bug 330707) links to a number of external sources.

this is problematic because we have no control over the content on these pages nor their availability, and in some cases isn't completely accurate (for example it states that we support github flavoured fenced code blocks, however we don't support language specific syntax highlighting).

all our supported markdown syntax should be documented on a bugzilla template page, and a 'help' link to this page should be added near the markdown checkbox.

Comment 1

[Simon Green]

Since it is related, on show_bug.cgi (and anywhere else the "Use Markdown for this comment" text appears), we should provide a link on the word 'Markdown' to the help text. 90% of users to Bugzilla won't know what Markdown is and the common syntax for it.

Comment 2

[:glob ✱]

(In reply to sgreen from comment #1)
> Since it is related, on show_bug.cgi (and anywhere else the "Use Markdown
> for this comment" text appears), we should provide a link on the word
> 'Markdown' to the help text. 90% of users to Bugzilla won't know what
> Markdown is and the common syntax for it.

i agree, except i think it should be a separate 'help' link instead of linking the word 'markdown' (see comment 0).

Comment 3

[Koosha KM]

How elaborate should it be? I believe something like the help on Github [1] with its concise format is good enough.

[1]: https://help.github.com/articles/markdown-basics

Comment 4

[Simon Green]

That github page is probably about perfect for our page.

Comment 5

[David Lawrence [:dkl]]

Koosha. I would like to get this in right before we branch for 5.0. What does your workload look like and do you feel like you will be able to work on this soon? If not I do not mind taking it over . Just let me know.

Thanks!
dkl

Comment 6

[Koosha KM]

(In reply to David Lawrence [:dkl] from comment #5)
> Koosha. I would like to get this in right before we branch for 5.0. What
> does your workload look like and do you feel like you will be able to work
> on this soon? If not I do not mind taking it over . Just let me know.
> 
> Thanks!
> dkl

I can start working on it very soon. I just wanted to first double check the code and make sure that everything works as expected, then write the user doc based on the rules followed by the markdown processor. I think we are now at a good stage to start writing it.

One question: should I write the doc under the same section of documentation or move it to somewhere else?

Comment 7

[David Lawrence [:dkl]]

(In reply to Koosha KM from comment #6)
> I can start working on it very soon. I just wanted to first double check the
> code and make sure that everything works as expected, then write the user
> doc based on the rules followed by the markdown processor. I think we are
> now at a good stage to start writing it.

Cool. Just wasn't sure if you were back on a full load at school or not :)

> One question: should I write the doc under the same section of documentation
> or move it to somewhere else?

We want it to be a page.cgi page so we can link to it from the markdown checkbox (help) link
from the show_bug.cgi page.

We should also mention the help page from the rST docs as well but no need to duplicate it.

Use template/en/default/pages/quicksearch.html.tmpl as an example (page.cgi?id=quicksearch.html)

dkl

Comment 8

[Koosha KM]

Attachment: patch_1059685_1

Comment 9

[David Lawrence [:dkl]]

Comment on attachment 8493191 [details] [diff] [review]
patch_1059685_1

Review of attachment 8493191 [details] [diff] [review]:
-----------------------------------------------------------------

Looks good! r=dkl

::: docs/en/rst/using.rst
@@ +798,5 @@
>  have your comments generated as HTML. For example, you may use Markdown for
>  making a part of your comment look italic or bold in the generated HTML. Bugzilla
>  supports most of the structures defined by `standard Markdown <http://daringfireball.net/projects/markdown/basics>`_.
> +but does NOT support inline images and inline HTML. For a complete reference on
> +supported Markdown structures, please see its syntax guide available at ``page.cgi?id=markdown.html``.

For a complete reference on  supported Markdown structures, please see the `syntax help <../../../page.cgi?id=markdown.html>`_
link next to the markdown checkbox for new comments.

Comment 10

[David Lawrence [:dkl]]

Thanks Koosha!

To ssh://[e-mail]/bugzilla/bugzilla.git
   1488a58..d416aab  master -> master

Comment 11

[David Lawrence [:dkl]]

Fixed error from t/008filter.t

To ssh://[e-mail]/bugzilla/bugzilla.git
   d416aab..e877bb3  master -> master