Commit d0481a65 authored by Vladimir Proshin's avatar Vladimir Proshin Committed by drugan

Initial commit

parents
# README Help module
This module in the first place is intented for developers. The
main feature of the module is reflected in its name:
> Forget about implementing `hook_help()` in `your_module.module` file. Just
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")
- [admin/help/readmehelp#markdown-text-filter](#markdown-filter
"Markdown Text Filter")
- [admin/help/readmehelp#advanced-readme-help](#advanced-readme-help
"Advanced README Help")
## 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")
```
Note that all raw text links, like http://php.net will be converted into:
```
http://php.net
#### Image
Relative Path:
!\[ALT Text]\(images/druplicon.png "Hover Title")
`...converted into:`
![ALT Text](images/druplicon.png "Hover Title")
Absolute Path:
!\[ALT Text](https://raw.githubusercontent.com/drugan/readmehelp/master/images/drupalcat.png
"Hover Title")
`...converted into:`
![ALT Text](https://raw.githubusercontent.com/drugan/readmehelp/master/images/drupalcat.png
"Hover Title")
> 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:
```
@PHPFILE: modules/contrib/readmehelp/readmehelp.module LINE:29 PADD:7 :PHPFILE@
```
> 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):
********************************************************************************
@PHPFILE: modules/contrib/readmehelp/readmehelp.module LINE:29 PADD:7 :PHPFILE@
********************************************************************************
## 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
implement easy to remember syntax for making their posts a bit richer while not
able to harm a site, whether intentionally or not.
> 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.
********************************************************************************
@PHPFILE: modules/contrib/readmehelp/readmehelp.module LINE:62 PADD:25 :PHPFILE@
********************************************************************************
###### Module author:
```
Vladimir Proshin (drugan)
[proshins@gmail.com](proshins@gmail.com)
[https://drupal.org/u/drugan](https://drupal.org/u/drugan)
```
{
"name": "drupal/readmehelp",
"type": "drupal-module",
"description": "Renders README file on the admin/help/your_module page",
"authors": [
{
"name": "Vladimir Proshin (drugan)",
"homepage": "https://www.drupal.org/u/drugan",
"role": "Maintainer"
}
],
"keywords": ["Drupal"],
"license": "GPL-2.0+",
"homepage": "https://www.drupal.org/project/readmehelp",
"minimum-stability": "dev",
"support": {
"issues": "https://www.drupal.org/project/issues/readmehelp",
"source": "http://cgit.drupalcode.org/readmehelp"
},
"require": { }
}
/**
* @file
* Stylesheet for the README Help module.
*
* Primer-product
* http://primercss.io
*
* Released under MIT license. Copyright 2015 GitHub, Inc.
*/
.readmehelp-100-width {
max-width: 100px;
}
.readmehelp-200-width {
max-width: 200px;
}
.readmehelp-300-width {
max-width: 300px;
}
.readmehelp-400-width {
max-width: 400px;
}
.readmehelp-500-width {
max-width: 500px;
}
.readmenelp-heading {
display: block;
padding: 9px 10px 10px;
margin: 0;
font-size: 14px;
line-height: 17px;
background-color: #f6f8fa;
border: 1px solid rgba(27,31,35,0.15);
border-bottom: 0;
border-radius: 3px 3px 0 0;
}
.markdown-body .markdown-image, .markdown-body .highlighted-snippet {
box-shadow: 1px 2px 5px 3px grey;
}
.markdown-body .highlighted-snippet {
padding: 0.5em;
}
.markdown-body {
padding:45px;
word-wrap:break-word;
background-color:#fff;
border:1px solid #ddd;
border-bottom-right-radius:3px;
border-bottom-left-radius:3px
}
.markdown-body {
font-family:-apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
font-size:16px;
line-height:1.5;
word-wrap:break-word
}
.markdown-body::before {
display:table;
content:""
}
.markdown-body::after {
display:table;
clear:both;
content:""
}
.markdown-body>*:first-child {
margin-top:0 !important
}
.markdown-body>*:last-child {
margin-bottom:0 !important
}
.markdown-body a:not([href]) {
color:inherit;
text-decoration:none
}
.markdown-body .absent {
color:#cb2431
}
.markdown-body .anchor {
float:left;
padding-right:4px;
/* margin-left:-20px; */
line-height:1
}
.markdown-body .anchor:focus {
outline:none
}
.markdown-body p,.markdown-body blockquote,.markdown-body cite,.markdown-body ul,.markdown-body ol,.markdown-body dl,.markdown-body table,.markdown-body pre {
margin-top:0;
margin-bottom:16px
}
.markdown-body hr {
padding:0;
margin:24px 0;
background-color:#e1e4e8;
border:0
}
.markdown-body hr.underscore {
height:0.25em;
}
.markdown-body hr.asterisk {
height:0.5em;
}
.markdown-body hr.dash {
height:0.75em;
}
.markdown-body blockquote, .markdown-body cite {
padding:0 1em;
color:#6a737d;
border-left:0.25em solid #dfe2e5
}
.markdown-body blockquote>:first-child, .markdown-body cite>:first-child {
margin-top:0
}
.markdown-body blockquote>:last-child, .markdown-body cite>:last-child {
margin-bottom:0
}
.markdown-body kbd {
display:inline-block;
padding:3px 5px;
font-size:11px;
line-height:10px;
color:#444d56;
vertical-align:middle;
background-color:#fafbfc;
border:solid 1px #c6cbd1;
border-bottom-color:#959da5;
border-radius:3px;
box-shadow:inset 0 -1px 0 #959da5
}
.markdown-body h1,.markdown-body h2,.markdown-body h3,.markdown-body h4,.markdown-body h5,.markdown-body h6 {
margin-top:24px;
margin-bottom:16px;
font-weight:600;
line-height:1.25
}
.markdown-body h1 .octicon-link,.markdown-body h2 .octicon-link,.markdown-body h3 .octicon-link,.markdown-body h4 .octicon-link,.markdown-body h5 .octicon-link,.markdown-body h6 .octicon-link {
color:#1b1f23;
vertical-align:middle;
visibility:hidden
}
.markdown-body h1:hover .anchor,.markdown-body h2:hover .anchor,.markdown-body h3:hover .anchor,.markdown-body h4:hover .anchor,.markdown-body h5:hover .anchor,.markdown-body h6:hover .anchor {
text-decoration:none
}
.markdown-body h1:hover .anchor .octicon-link,.markdown-body h2:hover .anchor .octicon-link,.markdown-body h3:hover .anchor .octicon-link,.markdown-body h4:hover .anchor .octicon-link,.markdown-body h5:hover .anchor .octicon-link,.markdown-body h6:hover .anchor .octicon-link {
visibility:visible
}
.markdown-body h1 tt,.markdown-body h1 code,.markdown-body h2 tt,.markdown-body h2 code,.markdown-body h3 tt,.markdown-body h3 code,.markdown-body h4 tt,.markdown-body h4 code,.markdown-body h5 tt,.markdown-body h5 code,.markdown-body h6 tt,.markdown-body h6 code {
font-size:inherit
}
.markdown-body h1 {
padding-bottom:0.3em;
font-size:2em;
border-bottom:1px solid #eaecef
}
.markdown-body h2 {
padding-bottom:0.3em;
font-size:1.5em;
border-bottom:1px solid #eaecef
}
.markdown-body h3 {
padding-bottom:0.3em;
font-size:1.25em;
border-bottom:1px solid #eaecef
}
.markdown-body h4 {
padding-bottom:0.3em;
font-size:1em;
border-bottom:1px solid #eaecef
}
.markdown-body h5 {
padding-bottom:0.3em;
font-size:0.875em;
border-bottom:1px solid #eaecef
}
.markdown-body h6 {
padding-bottom:0.3em;
font-size:0.85em;
border-bottom:1px solid #eaecef;
color:#6a737d;
}
.markdown-body ul,.markdown-body ol {
padding-left:2em
}
.markdown-body ul.no-list,.markdown-body ol.no-list {
padding:0;
list-style-type:none
}
.markdown-body ul ul,.markdown-body ul ol,.markdown-body ol ol,.markdown-body ol ul {
margin-top:0;
margin-bottom:0
}
.markdown-body li>p {
margin-top:16px
}
.markdown-body li+li {
margin-top:0.25em
}
.markdown-body dl {
padding:0
}
.markdown-body dl dt {
padding:0;
margin-top:16px;
font-size:1em;
font-style:italic;
font-weight:600
}
.markdown-body dl dd {
padding:0 16px;
margin-bottom:16px
}
.markdown-body table {
display:block;
width:100%;
overflow:auto
}
.markdown-body table th {
font-weight:600
}
.markdown-body table th,.markdown-body table td {
padding:6px 13px;
border:1px solid #dfe2e5
}
.markdown-body table tr {
background-color:#fff;
border-top:1px solid #c6cbd1
}
.markdown-body table tr:nth-child(2n) {
background-color:#f6f8fa
}
.markdown-body table img {
background-color:transparent
}
.markdown-body img {
max-width:100%;
box-sizing:content-box;
background-color:#fff
}
.markdown-body img[align=right] {
padding-left:20px
}
.markdown-body img[align=left] {
padding-right:20px
}
.markdown-body .emoji {
max-width:none;
vertical-align:text-top;
background-color:transparent
}
.markdown-body span.frame {
display:block;
overflow:hidden
}
.markdown-body span.frame>span {
display:block;
float:left;
width:auto;
padding:7px;
margin:13px 0 0;
overflow:hidden;
border:1px solid #dfe2e5
}
.markdown-body span.frame span img {
display:block;
float:left
}
.markdown-body span.frame span span {
display:block;
padding:5px 0 0;
clear:both;
color:#24292e
}
.markdown-body span.align-center {
display:block;
overflow:hidden;
clear:both
}
.markdown-body span.align-center>span {
display:block;
margin:13px auto 0;
overflow:hidden;
text-align:center
}
.markdown-body span.align-center span img {
margin:0 auto;
text-align:center
}
.markdown-body span.align-right {
display:block;
overflow:hidden;
clear:both
}
.markdown-body span.align-right>span {
display:block;
margin:13px 0 0;
overflow:hidden;
text-align:right
}
.markdown-body span.align-right span img {
margin:0;
text-align:right
}
.markdown-body span.float-left {
display:block;
float:left;
margin-right:13px;
overflow:hidden
}
.markdown-body span.float-left span {
margin:13px 0 0
}
.markdown-body span.float-right {
display:block;
float:right;
margin-left:13px;
overflow:hidden
}
.markdown-body span.float-right>span {
display:block;
margin:13px auto 0;
overflow:hidden;
text-align:right
}
.markdown-body code,.markdown-body tt {
padding:0;
padding-top:0.2em;
padding-bottom:0.2em;
margin:0;
font-size:85%;
background-color:rgba(27,31,35,0.05);
border-radius:3px
}
.markdown-body code::before,
.markdown-body code::after,
.markdown-body tt::before,.markdown-body tt::after {
letter-spacing:-0.2em;
content:"\00a0"
}
.markdown-body code br,.markdown-body tt br {
display:none
}
.markdown-body del code {
text-decoration:inherit
}
.markdown-body pre {
word-wrap:normal
}
.markdown-body pre>code {
padding:0;
margin:0;
font-size:100%;
word-break:normal;
white-space:pre;
background:transparent;
border:0