README.md 9.4 KB
Newer Older
Vladimir Proshin's avatar
Vladimir Proshin committed
1 2
# README Help module

drugan's avatar
drugan committed
3 4 5
Allows automatically to display module's *README* file on
the **admin/help/your_module** page. Provides [markdown ↗](https://en.wikipedia.org/wiki/Markdown)
text filter for creating text formats.
Vladimir Proshin's avatar
Vladimir Proshin committed
6

drugan's avatar
drugan committed
7 8 9 10 11 12 13
> Tip: you can see this file in your browser by clicking
the [admin/help#](#0 "? Help") link at the right of the *Admin toolbar* and then
the [admin/help/readmehelp#](#0 "README Help") link in the list.

________________________________________________________________________________

Forget about implementing `hook_help()` in `your_module.module` file. Just
Vladimir Proshin's avatar
Vladimir Proshin committed
14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36
write a decent *README* file with all information required and see it looking
almost the same both on the **admin/help/your_module** page as well in your text
editor. No more hardly to read (and to write!) markup intermingled with an
actual user help text. All that you need is just to add the `readmehelp`
dependency in `your_module.info.yml` and spend a couple of minutes learning the
basics of the markdown syntax:

- [admin/help/readmehelp#usage](#usage "Usage")
- [admin/help/readmehelp#markdown-special-symbols](#markdown-special-symbols
"Markdown special symbols")
- [admin/help/readmehelp#bold-and-italic-text](#bold-and-italic-text
"Bold and Italic Text")
- [admin/help/readmehelp#blockquote-and-cite](#blockquote-and-cite
"Blockquote and Cite")
- [admin/help/readmehelp#lists](#lists "Lists")
- [admin/help/readmehelp#anchor](#anchor "Anchor")
- [admin/help/readmehelp#image](#image "Image")
- [admin/help/readmehelp#horisontal-rule](#horisontal-rule "Horisontal Rule")
- [admin/help/readmehelp#headings](#headings "Headings")
- [admin/help/readmehelp#allowed-html-tags](#allowed-html-tags
"Allowed HTML tags")
- [admin/help/readmehelp#dynamic-php-snippets](#dynamic-php-snippets
"Dynamic PHP Snippets")
37
- [admin/help/readmehelp#markdown-text-filter](#markdown-text-filter
Vladimir Proshin's avatar
Vladimir Proshin committed
38 39 40
"Markdown Text Filter")
- [admin/help/readmehelp#advanced-readme-help](#advanced-readme-help
"Advanced README Help")
41 42 43
- [admin/help/readmehelp#module-author](#module-author "Module author")
- [README Help on drupal.org ↗](https://www.drupal.org/project/readmehelp)
- [README Help on github.com ↗](https://github.com/drugan/readmehelp)
Vladimir Proshin's avatar
Vladimir Proshin committed
44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180

## Usage

Open `your_module.info.yml` file and make it dependent on the `readmehelp`
module:

```yml
name: Your Module
type: module
description: Does awesome things.
core: 8.x
dependencies:
  - readmehelp
```

Then, if `your_module` is already installed on the site, just flush the caches.
If it's not, then the `readmehelp` will be installed automatically along with
`your_module`. That's it. You may skip further reading if you are already
familiar with markdown syntax or `your_module` help does not require complex
data compiling or multi-page help.

### Markdown special symbols

The *README Help* module's markdown syntax is a subset of the
[ Github Flavoured Markdown](
https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) syntax.
Whenever possible the module attempts to replicate the look and feel of
a *Github* repository's *README* file. Still, you may notice differences in some
places of the [admin/help/readmehelp#](#0 "file displayed on a Drupal site") or
on the [module's *Github* repository](https://github.com/drugan/readmehelp
"README Help on Github.com").

The markdown "tag" special symbols:

- The asterisk: **\***
- The backtick: **\`**
- The dash: **-**
- The underscore: **\_**
- The line leading hash: **\#**
- The line leading greater than symbol: **>**
- The line leading two greater than symbols: **>>**
- The line leading three and more symbols set: **\_\_\_**
- The line leading three and more symbols set: **\*\*\***
- The line leading three and more symbols set: **---**
- The line leading three and more symbols set: **===**
- The markdown anchor: **\[]()**
- The markdown image: **!\[]()**
- The markdown unordered list item: **\- ITEM**
- The markdown ordered list item: **1. ITEM**

If it is required to display markdown symbol as a regular character then the
backslash should be prepended to a symbol: **\SYMBOL**.

#### Bold and Italic Text

\*\*Bold\*\*

`...converted into:`

**Bold**

\_\_Bold\_\_

`...converted into:`

__Bold__

\*Italic\*

`...converted into:`

*Italic*

\_Italic\_

`...converted into:`

_Italic_

#### Blockquote and Cite

\> My Blockquote

`...converted into:`

> My Blockquote

\>\> My Cite

`...converted into:`

>> My Cite

```
Note that every blockquote or cite can be referenced directly both locally and
externally by using the clickable greater than (>) sign at the left of a
block.
```

#### Lists

\- ITEM

`...converted into:`

- ITEM

1.\ ITEM

`...converted into:`

1. ITEM

#### Anchor

Relative path:

> Notice hash (**#**) signs in the url.

\[admin/reports/dblog#](#0 "Reports")

`...converted into:`

[admin/reports/dblog#](#0 "Reports")

> Note that on the [github.com](https://github.com/drugan/readmehelp#anchor) the
link above will work just as a dummy link.

Absolute path:

\[PHP](http://php.net "On Hover Title")

`...converted into:`

[PHP](http://php.net/ "On Hover Title")

```
181
Note that any raw text url, like http://php.net will be converted into:
Vladimir Proshin's avatar
Vladimir Proshin committed
182 183 184 185 186 187 188 189
```
http://php.net


#### Image

Relative Path:

190
!\[ALT Text]\(images/druplicon.png "On Hover Title")
Vladimir Proshin's avatar
Vladimir Proshin committed
191 192 193

`...converted into:`

194
![ALT Text](images/druplicon.png "On Hover Title")
Vladimir Proshin's avatar
Vladimir Proshin committed
195 196 197

Absolute Path:

drugan's avatar
drugan committed
198
!\[ALT Text](https://raw.githubusercontent.com/drugan/readmehelp/8.x-1.x/images/drupalcat.png
199
"On Hover Title")
Vladimir Proshin's avatar
Vladimir Proshin committed
200 201 202

`...converted into:`

203
![ALT Text](https://raw.githubusercontent.com/drugan/readmehelp/8.x-1.x/images/drupalcat.png
204
"On Hover Title")
Vladimir Proshin's avatar
Vladimir Proshin committed
205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328

> See origin of the above image: https://octodex.github.com/images/drupalcat.jpg


#### Horisontal Rule

Three or more undescores like:

\_\_\_

`...converted into:`
________________________________________________________________________________


Three or more asterisks like:

\*\*\*

`...converted into:`

********************************************************************************


Three or more dashes like:

\-\-\-

`...converted into:`

--------------------------------------------------------------------------------

#### Headings

> Every heading can be referenced directly both locally and externally by
using the clickable hash (**#**) sign at the left of a heading.


`# H1`

```
Alternative H1
==============
```

`## H2`

```
Alternative H2
------------ -
```

`### H3`

`#### H4`

`##### H5`

`###### H6`


> Note that `# H1` and `Alternative H1` syntax can be used just once at the
very beginning of the file. So, demoing this heading is not possible here.

`...converted into:`

## H2

Alternative H2
--------------

### H3

#### H4

##### H5

###### H6


#### Allowed HTML tags

Besides the markdown a restricted set of *HTML* tags can be used for
building *README Help* files:

- a
- em
- strong
- cite
- blockquote
- code
- ul
- ol
- li
- dl
- dt
- dd
- img
- h1
- h2
- h3
- h4
- h5
- h6
- p
- pre
- hr
- table
- tr
- td
- div
- span

Also, [HTML Entities](https://dev.w3.org/html5/html-author/charref)
and [HTML comments](https://developer.mozilla.org/en-US/docs/Learn/HTML/Introduction_to_HTML/Getting_started#HTML_comments)
are supported.

<!-- This text is not visible on the admin/help/your_module page -->

#### Dynamic PHP Snippets

To insert higlighted snippet of any existing on a Drupal site PHP file you need
to construct a token like the following:

```
329
@PHPFILE: modules/contrib/readmehelp/readmehelp.module LINE:26 PADD:7 :PHPFILE@
Vladimir Proshin's avatar
Vladimir Proshin committed
330 331
```

332 333 334
`...or just:`

```
335
@PHPFILE: readmehelp.module LINE:26 PADD:7 :PHPFILE@
336 337
```

Vladimir Proshin's avatar
Vladimir Proshin committed
338 339 340 341 342 343 344 345 346 347 348
> The absolute or relative path to a file may be followed by a **LINE** number
argument and **PADD**, which is the number of lines to add before and after
the **LINE** (additionally highlighted with yellow color). Both arguments are
optional. If no **PADD** is passed then the default **10** lines will be added.
If no **LINE** is passed then a whole highlighted file will be returned. There
is a replacement of the token above (on
the [github.com](https://github.com/drugan/readmehelp#dynamic-php-snippets
"README Help Github repository") shown as a raw token):

********************************************************************************

349
@PHPFILE: readmehelp.module LINE:26 PADD:7 :PHPFILE@
Vladimir Proshin's avatar
Vladimir Proshin committed
350 351 352 353 354 355 356 357

********************************************************************************

## Markdown Text Filter

*README Help* module has its own [filter/tips#readmehelp-filter](#0
"markdown text filter") which could be used for creating
[admin/config/content/formats#](#0 " Drupal text formats"). So, users can
358 359
implement easy to remember syntax for making their posts richer while not able
to harm a site, whether intentionally or not.
Vladimir Proshin's avatar
Vladimir Proshin committed
360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375

> Note that no any of the external libraries are used by the filter.

## Advanced README Help

There might be cases when you still need to implement `hook_help()` and at the
same time leverage the power of the *README Help* module. To restore the default
behaviour you need additionally to implement dummy `your_module_readmehelp()`
which disables automatic rendering of your module's *README* file and instead
calls the regular `your_module_help()`.

Copy the code from the snippet below, insert it into `your_module.module` file
and edit for your needs.

********************************************************************************

376
@PHPFILE: your_module.module.example LINE:33 PADD:33 :PHPFILE@
Vladimir Proshin's avatar
Vladimir Proshin committed
377 378 379 380 381

********************************************************************************

###### Module author:
```
drugan's avatar
drugan committed
382
  Vlad Proshin (drugan)
Vladimir Proshin's avatar
Vladimir Proshin committed
383 384 385
  [proshins@gmail.com](proshins@gmail.com)
  [https://drupal.org/u/drugan](https://drupal.org/u/drugan)
```