github-markup 3.0.1 → 3.0.2
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/.dockerignore +1 -0
- data/.gitignore +1 -1
- data/.gitmodules +3 -0
- data/.travis.yml +4 -1
- data/Dockerfile +39 -0
- data/HISTORY.md +4 -0
- data/README.md +11 -2
- data/github-markup.gemspec +2 -1
- data/lib/github-markup.rb +1 -1
- data/lib/github/commands/pod62html +10 -0
- data/lib/github/markup.rb +1 -0
- data/lib/github/markup/implementation.rb +5 -1
- data/lib/github/markups.rb +1 -0
- data/test/markup_test.rb +2 -3
- data/test/markups/README.pod6 +151 -0
- data/test/markups/README.pod6.html +128 -0
- data/vendor/Pod-To-HTML/LICENSE +201 -0
- data/vendor/Pod-To-HTML/META6.json +20 -0
- data/vendor/Pod-To-HTML/README.md +96 -0
- data/vendor/Pod-To-HTML/README.pod6 +42 -0
- data/vendor/Pod-To-HTML/TODO +5 -0
- data/vendor/Pod-To-HTML/lib/Pod/To/HTML.pm +691 -0
- data/vendor/Pod-To-HTML/resources/examples/01-parse-files.p6 +7 -0
- data/vendor/Pod-To-HTML/resources/examples/README.md +13 -0
- data/vendor/Pod-To-HTML/resources/examples/main.mustache +26 -0
- data/vendor/Pod-To-HTML/resources/examples/render.p6 +17 -0
- data/vendor/Pod-To-HTML/resources/templates/main.mustache +32 -0
- data/vendor/Pod-To-HTML/t/010-basic.t +29 -0
- data/vendor/Pod-To-HTML/t/020-code.t +49 -0
- data/vendor/Pod-To-HTML/t/030-comment.t +15 -0
- data/vendor/Pod-To-HTML/t/040-lists.t +82 -0
- data/vendor/Pod-To-HTML/t/050-format-x-index.t +47 -0
- data/vendor/Pod-To-HTML/t/060-table.t +108 -0
- data/vendor/Pod-To-HTML/t/070-headings.t +45 -0
- data/vendor/Pod-To-HTML/t/075-defn.t +45 -0
- data/vendor/Pod-To-HTML/t/080-lang.t +14 -0
- data/vendor/Pod-To-HTML/t/090-css.t +16 -0
- data/vendor/Pod-To-HTML/t/100-issue-37.t +16 -0
- data/vendor/Pod-To-HTML/t/110-issue-41.t +18 -0
- data/vendor/Pod-To-HTML/t/120-templates.t +42 -0
- data/vendor/Pod-To-HTML/t/templates/main.mustache +33 -0
- metadata +39 -6
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 4a1ac869e4b4e23a417481b72789919fcfd5f7681a7109d13b58436bdf686b3a
|
4
|
+
data.tar.gz: b3e9e1e23c8f3253fc1c169a76839b06ded3f121442c063acb7a0c9704772631
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 13f584545ee0d79316a3f68d080b3f0c44a31a1b8e23468ed3b8da611d4933bb6eeb183c29b918484d1218cb132a3dbd77ca87fd4c5bc89bd53738a1c1b04cfa
|
7
|
+
data.tar.gz: 63977e1c80e89c7d976dae9c119b1f28c5c27e3066f8cd610d31e9ef3a61d3531fffd323b729c16446eb8abf3ec19d92bb321e0fa5a5503b1a8198461031a8b8
|
data/.dockerignore
ADDED
@@ -0,0 +1 @@
|
|
1
|
+
Dockerfile
|
data/.gitignore
CHANGED
data/.gitmodules
ADDED
data/.travis.yml
CHANGED
@@ -14,8 +14,11 @@ notifications:
|
|
14
14
|
git:
|
15
15
|
depth: 10
|
16
16
|
before_install:
|
17
|
+
- sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 379CE192D401AB61
|
18
|
+
- echo "deb https://dl.bintray.com/nxadm/rakudo-pkg-debs `lsb_release -cs` main" | sudo tee -a /etc/apt/sources.list.d/rakudo-pkg.list
|
17
19
|
- sudo apt-get update -qq
|
18
|
-
- sudo apt-get install perl
|
20
|
+
- sudo apt-get install perl rakudo-pkg
|
21
|
+
- export PATH=$PATH:/.perl6/bin:/opt/rakudo-pkg/bin && install-zef-as-user && zef install Pod::To::HTML
|
19
22
|
- curl -L http://cpanmin.us | perl - --sudo App::cpanminus
|
20
23
|
- sudo cpanm --installdeps --notest Pod::Simple
|
21
24
|
- sudo pip install docutils
|
data/Dockerfile
ADDED
@@ -0,0 +1,39 @@
|
|
1
|
+
FROM ubuntu:trusty
|
2
|
+
|
3
|
+
RUN apt-get update -qq
|
4
|
+
RUN apt-get install -y apt-transport-https
|
5
|
+
|
6
|
+
RUN apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 379CE192D401AB61
|
7
|
+
RUN echo "deb https://dl.bintray.com/nxadm/rakudo-pkg-debs `lsb_release -cs` main" | tee -a /etc/apt/sources.list.d/rakudo-pkg.list
|
8
|
+
RUN apt-get update -qq
|
9
|
+
|
10
|
+
RUN apt-get install -y \
|
11
|
+
perl rakudo-pkg curl git build-essential python python-pip \
|
12
|
+
libssl-dev libreadline-dev zlib1g-dev \
|
13
|
+
libicu-dev cmake pkg-config
|
14
|
+
|
15
|
+
ENV PATH $PATH:/opt/rakudo-pkg/bin
|
16
|
+
RUN install-zef-as-user && zef install Pod::To::HTML
|
17
|
+
|
18
|
+
RUN curl -L http://cpanmin.us | perl - App::cpanminus
|
19
|
+
RUN cpanm --installdeps --notest Pod::Simple
|
20
|
+
|
21
|
+
RUN pip install docutils
|
22
|
+
|
23
|
+
ENV PATH $PATH:/root/.rbenv/bin:/root/.rbenv/shims
|
24
|
+
RUN curl -fsSL https://github.com/rbenv/rbenv-installer/raw/master/bin/rbenv-installer | bash
|
25
|
+
RUN rbenv install 2.4.1
|
26
|
+
RUN rbenv global 2.4.1
|
27
|
+
RUN rbenv rehash
|
28
|
+
|
29
|
+
RUN gem install bundler
|
30
|
+
|
31
|
+
WORKDIR /data/github-markup
|
32
|
+
COPY github-markup.gemspec .
|
33
|
+
COPY Gemfile .
|
34
|
+
COPY Gemfile.lock .
|
35
|
+
COPY lib/github-markup.rb lib/github-markup.rb
|
36
|
+
RUN bundle
|
37
|
+
|
38
|
+
ENV LC_ALL en_US.UTF-8
|
39
|
+
RUN locale-gen en_US.UTF-8
|
data/HISTORY.md
CHANGED
data/README.md
CHANGED
@@ -6,7 +6,7 @@ This library is the **first step** of a journey that every markup file in a repo
|
|
6
6
|
1. `github-markup` selects an _underlying library_ to convert the raw markup to HTML. See the list of [supported markup formats](#markups) below.
|
7
7
|
1. The HTML is sanitized, aggressively removing things that could harm you and your kin—such as `script` tags, inline-styles, and `class` or `id` attributes.
|
8
8
|
1. Syntax highlighting is performed on code blocks. See [github/linguist](https://github.com/github/linguist#syntax-highlighting) for more information about syntax highlighting.
|
9
|
-
1. The HTML is passed through other filters
|
9
|
+
1. The HTML is passed through other filters that add special sauce, such as emoji, task lists, named anchors, CDN caching for images, and autolinking.
|
10
10
|
1. The resulting HTML is rendered on GitHub.com.
|
11
11
|
|
12
12
|
Please note that **only the first step** is covered by this gem — the rest happens on GitHub.com. In particular, `markup` itself does no sanitization of the resulting HTML, as it expects that to be covered by whatever pipeline is consuming the HTML.
|
@@ -29,7 +29,8 @@ you wish to run the library. You can also run `script/bootstrap` to fetch them a
|
|
29
29
|
* [.asciidoc, .adoc, .asc](http://asciidoc.org/) -- `gem install asciidoctor` (http://asciidoctor.org)
|
30
30
|
* [.pod](http://search.cpan.org/dist/perl/pod/perlpod.pod) -- `Pod::Simple::XHTML`
|
31
31
|
comes with Perl >= 5.10. Lower versions should install Pod::Simple from CPAN.
|
32
|
-
|
32
|
+
* [.pod6](https://docs.perl6.org/language/pod) -- No additional
|
33
|
+
dependency beyond perl6 `Pod::To::HTML` (in stdlib)
|
33
34
|
|
34
35
|
Installation
|
35
36
|
-----------
|
@@ -38,6 +39,14 @@ Installation
|
|
38
39
|
gem install github-markup
|
39
40
|
```
|
40
41
|
|
42
|
+
or
|
43
|
+
|
44
|
+
```
|
45
|
+
bundle install
|
46
|
+
```
|
47
|
+
|
48
|
+
from this directory.
|
49
|
+
|
41
50
|
Usage
|
42
51
|
-----
|
43
52
|
|
data/github-markup.gemspec
CHANGED
@@ -12,6 +12,7 @@ Gem::Specification.new do |s|
|
|
12
12
|
s.license = "MIT"
|
13
13
|
|
14
14
|
s.files = `git ls-files`.split($\)
|
15
|
+
s.files += Dir['vendor/Pod-To-HTML/**/*']
|
15
16
|
s.executables = s.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
|
16
17
|
s.test_files = s.files.grep(%r{^(test|spec|features)/})
|
17
18
|
s.require_paths = %w[lib]
|
@@ -23,5 +24,5 @@ Gem::Specification.new do |s|
|
|
23
24
|
s.add_development_dependency 'sanitize', '~> 2.1', '>= 2.1.0'
|
24
25
|
s.add_development_dependency 'nokogiri', '~> 1.8.1'
|
25
26
|
s.add_development_dependency 'nokogiri-diff', '~> 0.2.0'
|
26
|
-
s.add_development_dependency "github-linguist", "
|
27
|
+
s.add_development_dependency "github-linguist", ">= 7.1.3"
|
27
28
|
end
|
data/lib/github-markup.rb
CHANGED
@@ -0,0 +1,10 @@
|
|
1
|
+
#!/usr/bin/env perl6
|
2
|
+
|
3
|
+
use v6;
|
4
|
+
use lib $*PROGRAM.IO.parent.add: '../../../vendor/Pod-To-HTML';
|
5
|
+
use Pod::To::HTML;
|
6
|
+
|
7
|
+
$_ = Pod::To::HTML.render(slurp);
|
8
|
+
s:s{\<\!doctype html\>.*\<div id\=\"___top\"\>\<\/div\>\s*} = "";
|
9
|
+
s:s{\s*\<\/div\>\s*\<\/body\>\s*\<\/html\>\s*} = "";
|
10
|
+
.put;
|
data/lib/github/markup.rb
CHANGED
@@ -8,7 +8,11 @@ module GitHub
|
|
8
8
|
@regexp = regexp
|
9
9
|
|
10
10
|
if defined?(::Linguist)
|
11
|
-
@languages = languages.map
|
11
|
+
@languages = languages.map do |l|
|
12
|
+
lang = Linguist::Language[l]
|
13
|
+
raise "no match for language #{l.inspect}" if lang.nil?
|
14
|
+
lang
|
15
|
+
end
|
12
16
|
end
|
13
17
|
end
|
14
18
|
|
data/lib/github/markups.rb
CHANGED
data/test/markup_test.rb
CHANGED
@@ -52,7 +52,6 @@ class MarkupTest < Minitest::Test
|
|
52
52
|
|
53
53
|
define_method "test_#{markup}" do
|
54
54
|
skip "Skipping MediaWiki test because wikicloth is currently not compatible with JRuby." if markup == "mediawiki" && RUBY_PLATFORM == "java"
|
55
|
-
|
56
55
|
source = File.read(readme)
|
57
56
|
expected_file = "#{readme}.html"
|
58
57
|
expected = File.read(expected_file).rstrip
|
@@ -67,7 +66,6 @@ class MarkupTest < Minitest::Test
|
|
67
66
|
f.close_write
|
68
67
|
f.read
|
69
68
|
end
|
70
|
-
|
71
69
|
assert_html_equal expected, actual, <<message
|
72
70
|
#{File.basename expected_file}'s contents are not html equal to output:
|
73
71
|
#{diff}
|
@@ -91,7 +89,8 @@ message
|
|
91
89
|
assert_equal "wikicloth", GitHub::Markup.renderer('README.wiki', '<h1>Title</h1>').name
|
92
90
|
assert_equal "asciidoctor", GitHub::Markup.renderer('README.adoc', '== Title').name
|
93
91
|
assert_equal "restructuredtext", GitHub::Markup.renderer('README.rst', 'Title').name
|
94
|
-
assert_equal "pod", GitHub::Markup.renderer('README.pod', '=
|
92
|
+
assert_equal "pod", GitHub::Markup.renderer('README.pod', '=head1').name
|
93
|
+
assert_equal "pod6", GitHub::Markup.renderer('README.pod6', '=begin pod').name
|
95
94
|
end
|
96
95
|
|
97
96
|
def test_rendering_by_symbol
|
@@ -0,0 +1,151 @@
|
|
1
|
+
=begin pod
|
2
|
+
|
3
|
+
=TITLE About the Docs
|
4
|
+
|
5
|
+
=SUBTITLE Meta-documentation
|
6
|
+
|
7
|
+
This document collection represents the on-going effort to document the Perl 6 programming
|
8
|
+
language with the goals of being: comprehensive; easy to use; easy to
|
9
|
+
navigate; and useful to both newcomers and experienced Perl 6
|
10
|
+
programmers.
|
11
|
+
|
12
|
+
An HTML version of the documentation is located online at
|
13
|
+
L<https://docs.perl6.org>.
|
14
|
+
|
15
|
+
The official source for this documentation is located at L<perl6/doc on
|
16
|
+
GitHub|https://github.com/perl6/doc>.
|
17
|
+
|
18
|
+
This particular document is a quick overview of the process
|
19
|
+
described in more detail in L<CONTRIBUTING on GitHub|https://github.com/perl6/doc/blob/master/CONTRIBUTING.md>.
|
20
|
+
This document also provides a short introduction to writing Perl 6
|
21
|
+
Pod files, which can be rendered into HTML and other formats.
|
22
|
+
|
23
|
+
=head1 Structure
|
24
|
+
|
25
|
+
All of the documentation is written in Perl 6 Pod and kept in the C<doc/>
|
26
|
+
directory, and the C<doc/Language/> and C<doc/Type/> sub-directories.
|
27
|
+
These files are processed as collections of definitions or
|
28
|
+
"documentables", which are then post-processed and linked together.
|
29
|
+
|
30
|
+
=head1 Generating HTML from Pod
|
31
|
+
|
32
|
+
To generate HTML from the Pod files, you'll need:
|
33
|
+
|
34
|
+
=item A recent version of the Rakudo Perl 6 compiler
|
35
|
+
|
36
|
+
=item The Perl 6 modules Pod::To::HTML, Pod::To::BigPage, and URI::Escape
|
37
|
+
(can be installed via L<zef|https://github.com/ugexe/zef>).
|
38
|
+
|
39
|
+
=item B<Optional>: L<GraphViz|http://graphviz.org>, for creating graphs
|
40
|
+
of the relationships between Perl 6 types
|
41
|
+
|
42
|
+
=item B<Optional>: L<Atom Highlights|https://github.com/atom/highlights> and L<language-perl6|https://atom.io/packages/language-perl6>, for syntax
|
43
|
+
highlighting
|
44
|
+
|
45
|
+
To generate the documentation into the C<html/> folder, run:
|
46
|
+
|
47
|
+
=begin code :lang<shell>
|
48
|
+
perl6 htmlify.p6
|
49
|
+
=end code
|
50
|
+
|
51
|
+
To host the documentation from a web server, have Perl 5
|
52
|
+
and Mojolicious::Lite installed, then run:
|
53
|
+
|
54
|
+
=begin code :lang<shell>
|
55
|
+
perl app.pl daemon
|
56
|
+
=end code
|
57
|
+
|
58
|
+
=head1 Contributing
|
59
|
+
|
60
|
+
The documentation is written in Perl 6 Pod.
|
61
|
+
|
62
|
+
For a quick introduction to Perl 6 Pod, see L<Perl 6 Pod|https://docs.perl6.org/language/pod>.
|
63
|
+
|
64
|
+
For full details about the Perl 6 Pod specification, see L<Synopsis 26, Documentation|https://design.perl6.org/S26.html>.
|
65
|
+
|
66
|
+
=head2 Adding definitions
|
67
|
+
|
68
|
+
Documentables can be defined using an C<=headN> Pod directive, where
|
69
|
+
C<N> is greater than zero (e.g., C<=head1>, C<=head2>, …).
|
70
|
+
|
71
|
+
All of the paragraphs and blocks following that directive, up until the
|
72
|
+
next directive of the same level, will be considered part of the
|
73
|
+
documentable. So, in:
|
74
|
+
|
75
|
+
=begin code :allow<R> :skip-test
|
76
|
+
=head2 R<My Definition>
|
77
|
+
|
78
|
+
Some paragraphs, followed by some code:
|
79
|
+
|
80
|
+
my Code $examples = "amazing";
|
81
|
+
|
82
|
+
Mind === blown.
|
83
|
+
|
84
|
+
=head3 Minor details about R<My Definition>
|
85
|
+
|
86
|
+
It's fantastic.
|
87
|
+
|
88
|
+
=head2 And now, for something completely different
|
89
|
+
|
90
|
+
…
|
91
|
+
|
92
|
+
=end code
|
93
|
+
|
94
|
+
The documentable R<My Definition> extends down to the C<=head2 And now…>.
|
95
|
+
|
96
|
+
Documentables may contain other documentables. Class documentables, for
|
97
|
+
example, often contain the methods the class implements.
|
98
|
+
|
99
|
+
Definitions must be in one of the following forms to be recognized as
|
100
|
+
the start of a documentable named, say, þ. First the code in the document source:
|
101
|
+
|
102
|
+
=begin code :skip-test
|
103
|
+
|
104
|
+
=item X<C<How to use the þ infix> | infix,þ> (This a special case, which
|
105
|
+
is always considered a definition)
|
106
|
+
|
107
|
+
=item C<The þ Infix>
|
108
|
+
|
109
|
+
=item B<The C<þ> Infix>
|
110
|
+
|
111
|
+
=item C<Infix þ>
|
112
|
+
|
113
|
+
=item B<Infix C<þ>>
|
114
|
+
|
115
|
+
=item C<trait is cached> (A special case for the L<trait|/language/functions#Traits> documentables)
|
116
|
+
|
117
|
+
=end code
|
118
|
+
|
119
|
+
Then the results on the rendered page:
|
120
|
+
|
121
|
+
=item X<C<How to use the þ infix> | infix,þ> (This is a special case, which
|
122
|
+
is always considered a definition)
|
123
|
+
|
124
|
+
=item C<The þ Infix>
|
125
|
+
|
126
|
+
=item B<The C<þ> Infix>
|
127
|
+
|
128
|
+
=item C<Infix þ>
|
129
|
+
|
130
|
+
=item B<Infix C<þ>>
|
131
|
+
|
132
|
+
=item C<trait is cached> (A special case for the L<trait|/language/functions#Traits> documentables)
|
133
|
+
|
134
|
+
These items should now be searchable by using the search field in the HTML docs.
|
135
|
+
|
136
|
+
You can add emphasis with bold (B<V< B<> >>) or italicized (B<V< I<> >>),
|
137
|
+
with or without code formatting (B<V< C<> >>). Due to current parser limitations,
|
138
|
+
special steps have to be taken to use B<V< X<> >> with other formatting codes; for example:
|
139
|
+
|
140
|
+
=begin code :skip-test
|
141
|
+
=item X<B<foo>|foo> a fancy subroutine
|
142
|
+
=end code
|
143
|
+
|
144
|
+
renders like this
|
145
|
+
|
146
|
+
=item X<B<foo>|foo> a fancy subroutine
|
147
|
+
|
148
|
+
Notice that text after a pipe ('|') has no formatting. Also note that B<V< C<> >>
|
149
|
+
preserves spaces and treats text as verbatim.
|
150
|
+
=end pod
|
151
|
+
|
@@ -0,0 +1,128 @@
|
|
1
|
+
<h1>About the Docs</h1>
|
2
|
+
<p>Meta-documentation</p>
|
3
|
+
|
4
|
+
<table>
|
5
|
+
<h2>Table of Contents</h2>
|
6
|
+
<tr>
|
7
|
+
<td>1</td>
|
8
|
+
<td><a href="#Structure">Structure</a></td>
|
9
|
+
</tr>
|
10
|
+
<tr>
|
11
|
+
<td>2</td>
|
12
|
+
<td><a href="#Generating_HTML_from_Pod">Generating HTML from Pod</a></td>
|
13
|
+
</tr>
|
14
|
+
<tr>
|
15
|
+
<td>3</td>
|
16
|
+
<td><a href="#Contributing">Contributing</a></td>
|
17
|
+
</tr>
|
18
|
+
<tr>
|
19
|
+
<td>3.1</td>
|
20
|
+
<td><a href="#Adding_definitions">Adding definitions</a></td>
|
21
|
+
</tr>
|
22
|
+
|
23
|
+
</table>
|
24
|
+
|
25
|
+
|
26
|
+
<div>
|
27
|
+
<p>This document collection represents the on-going effort to document the Perl 6 programming language with the goals of being: comprehensive; easy to use; easy to navigate; and useful to both newcomers and experienced Perl 6 programmers.</p>
|
28
|
+
<p>An HTML version of the documentation is located online at <a href="https://docs.perl6.org">https://docs.perl6.org</a>.</p>
|
29
|
+
<p>The official source for this documentation is located at <a href="https://github.com/perl6/doc">perl6/doc on GitHub</a>.</p>
|
30
|
+
<p>This particular document is a quick overview of the process described in more detail in <a href="https://github.com/perl6/doc/blob/master/CONTRIBUTING.md">CONTRIBUTING on GitHub</a>. This document also provides a short introduction to writing Perl 6 Pod files, which can be rendered into HTML and other formats.</p>
|
31
|
+
<h1><a href="#___top" title="go to top of document">Structure</a></h1>
|
32
|
+
<p>All of the documentation is written in Perl 6 Pod and kept in the <code>doc/</code> directory, and the <code>doc/Language/</code> and <code>doc/Type/</code> sub-directories. These files are processed as collections of definitions or "documentables", which are then post-processed and linked together.</p>
|
33
|
+
<h1><a href="#___top" title="go to top of document">Generating HTML from Pod</a></h1>
|
34
|
+
<p>To generate HTML from the Pod files, you'll need:</p>
|
35
|
+
<ul>
|
36
|
+
<li>
|
37
|
+
<p>A recent version of the Rakudo Perl 6 compiler</p>
|
38
|
+
</li>
|
39
|
+
<li>
|
40
|
+
<p>The Perl 6 modules Pod::To::HTML, Pod::To::BigPage, and URI::Escape (can be installed via <a href="https://github.com/ugexe/zef">zef</a>).</p>
|
41
|
+
</li>
|
42
|
+
<li>
|
43
|
+
<p><strong>Optional</strong>: <a href="http://graphviz.org">GraphViz</a>, for creating graphs of the relationships between Perl 6 types</p>
|
44
|
+
</li>
|
45
|
+
<li>
|
46
|
+
<p><strong>Optional</strong>: <a href="https://github.com/atom/highlights">Atom Highlights</a> and <a href="https://atom.io/packages/language-perl6">language-perl6</a>, for syntax highlighting</p>
|
47
|
+
</li>
|
48
|
+
</ul>
|
49
|
+
<p>To generate the documentation into the <code>html/</code> folder, run:</p>
|
50
|
+
<pre>perl6 htmlify.p6
|
51
|
+
</pre>
|
52
|
+
<p>To host the documentation from a web server, have Perl 5 and Mojolicious::Lite installed, then run:</p>
|
53
|
+
<pre>perl app.pl daemon
|
54
|
+
</pre>
|
55
|
+
<h1><a href="#___top" title="go to top of document">Contributing</a></h1>
|
56
|
+
<p>The documentation is written in Perl 6 Pod.</p>
|
57
|
+
<p>For a quick introduction to Perl 6 Pod, see <a href="https://docs.perl6.org/language/pod">Perl 6 Pod</a>.</p>
|
58
|
+
<p>For full details about the Perl 6 Pod specification, see <a href="https://design.perl6.org/S26.html">Synopsis 26, Documentation</a>.</p>
|
59
|
+
<h2><a href="#___top" title="go to top of document">Adding definitions</a></h2>
|
60
|
+
<p>Documentables can be defined using an <code>=headN</code> Pod directive, where <code>N</code> is greater than zero (e.g., <code>=head1</code>, <code>=head2</code>, …).</p>
|
61
|
+
<p>All of the paragraphs and blocks following that directive, up until the next directive of the same level, will be considered part of the documentable. So, in:</p>
|
62
|
+
<pre>=head2 <var>My Definition</var>
|
63
|
+
|
64
|
+
Some paragraphs, followed by some code:
|
65
|
+
|
66
|
+
my Code $examples = "amazing";
|
67
|
+
|
68
|
+
Mind === blown.
|
69
|
+
|
70
|
+
=head3 Minor details about <var>My Definition</var>
|
71
|
+
|
72
|
+
It's fantastic.
|
73
|
+
|
74
|
+
=head2 And now, for something completely different
|
75
|
+
|
76
|
+
…
|
77
|
+
|
78
|
+
</pre>
|
79
|
+
<p>The documentable <var>My Definition</var> extends down to the <code>=head2 And now…</code>.</p>
|
80
|
+
<p>Documentables may contain other documentables. Class documentables, for example, often contain the methods the class implements.</p>
|
81
|
+
<p>Definitions must be in one of the following forms to be recognized as the start of a documentable named, say, þ. First the code in the document source:</p>
|
82
|
+
<pre>=item X<C<How to use the þ infix> | infix,þ> (This a special case, which
|
83
|
+
is always considered a definition)
|
84
|
+
|
85
|
+
=item C<The þ Infix>
|
86
|
+
|
87
|
+
=item B<The C<þ> Infix>
|
88
|
+
|
89
|
+
=item C<Infix þ>
|
90
|
+
|
91
|
+
=item B<Infix C<þ>>
|
92
|
+
|
93
|
+
=item C<trait is cached> (A special case for the L<trait|/language/functions#Traits> documentables)
|
94
|
+
|
95
|
+
</pre>
|
96
|
+
<p>Then the results on the rendered page:</p>
|
97
|
+
<ul>
|
98
|
+
<li>
|
99
|
+
<p><a name="index-entry-infix_%C3%BE-How_to_use_the_%C3%BE_infix"><code>How to use the þ infix</code></a> (This is a special case, which is always considered a definition)</p>
|
100
|
+
</li>
|
101
|
+
<li>
|
102
|
+
<p><code>The þ Infix</code></p>
|
103
|
+
</li>
|
104
|
+
<li>
|
105
|
+
<p><strong>The <code>þ</code> Infix</strong></p>
|
106
|
+
</li>
|
107
|
+
<li>
|
108
|
+
<p><code>Infix þ</code></p>
|
109
|
+
</li>
|
110
|
+
<li>
|
111
|
+
<p><strong>Infix <code>þ</code></strong></p>
|
112
|
+
</li>
|
113
|
+
<li>
|
114
|
+
<p><code>trait is cached</code> (A special case for the <a href="/language/functions#Traits">trait</a> documentables)</p>
|
115
|
+
</li>
|
116
|
+
</ul>
|
117
|
+
<p>These items should now be searchable by using the search field in the HTML docs.</p>
|
118
|
+
<p>You can add emphasis with bold (<strong> B<> </strong>) or italicized (<strong> I<> </strong>), with or without code formatting (<strong> C<> </strong>). Due to current parser limitations, special steps have to be taken to use <strong> X<> </strong> with other formatting codes; for example:</p>
|
119
|
+
<pre>=item X<B<foo>|foo> a fancy subroutine
|
120
|
+
</pre>
|
121
|
+
<p>renders like this</p>
|
122
|
+
<ul>
|
123
|
+
<li>
|
124
|
+
<p><a name="index-entry-foo-foo"><strong>foo</strong></a> a fancy subroutine</p>
|
125
|
+
</li>
|
126
|
+
</ul>
|
127
|
+
<p>Notice that text after a pipe ('|') has no formatting. Also note that <strong> C<> </strong> preserves spaces and treats text as verbatim.</p>
|
128
|
+
</div>
|