Merge pull request #1173 from JJ/master

Adds POD6, the markup language for Perl6, to the repo
github · Dec 12, 2018 · 83d9824 · 83d9824
2 parents 11a355b + 455a75d
commit 83d9824
Show file tree

Hide file tree

Showing 15 changed files with 359 additions and 8 deletions.
diff --git a/.dockerignore b/.dockerignore
@@ -0,0 +1 @@
+Dockerfile
diff --git a/.gitignore b/.gitignore
@@ -2,6 +2,6 @@
 pkg/
 .bundle
 Gemfile.lock
-vendor/
 .project
 .buildpath
+*~ 
diff --git a/.gitmodules b/.gitmodules
@@ -0,0 +1,3 @@
+[submodule "vendor/Pod-To-HTML"]
+	path = vendor/Pod-To-HTML
+	url = https://github.com/perl6/Pod-To-HTML
diff --git a/.travis.yml b/.travis.yml
@@ -14,8 +14,11 @@ notifications:
 git:
   depth: 10
 before_install:
+  - sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 379CE192D401AB61
+  - 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
   - sudo apt-get update -qq
-  - sudo apt-get install perl
+  - sudo apt-get install perl rakudo-pkg
+  - export PATH=$PATH:/.perl6/bin:/opt/rakudo-pkg/bin && install-zef-as-user && zef install Pod::To::HTML
   - curl -L http://cpanmin.us | perl - --sudo App::cpanminus
   - sudo cpanm --installdeps --notest Pod::Simple
   - sudo pip install docutils

diff --git a/Dockerfile b/Dockerfile
@@ -0,0 +1,39 @@
+FROM ubuntu:trusty
+
+RUN apt-get update -qq
+RUN apt-get install -y apt-transport-https
+
+RUN apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 379CE192D401AB61
+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
+RUN apt-get update -qq
+
+RUN apt-get install -y \
+    perl rakudo-pkg curl git build-essential python python-pip \
+    libssl-dev libreadline-dev zlib1g-dev \
+    libicu-dev cmake pkg-config
+
+ENV PATH $PATH:/opt/rakudo-pkg/bin
+RUN install-zef-as-user && zef install Pod::To::HTML
+
+RUN curl -L http://cpanmin.us | perl - App::cpanminus
+RUN cpanm --installdeps --notest Pod::Simple
+
+RUN pip install docutils
+
+ENV PATH $PATH:/root/.rbenv/bin:/root/.rbenv/shims
+RUN curl -fsSL https://github.com/rbenv/rbenv-installer/raw/master/bin/rbenv-installer | bash
+RUN rbenv install 2.4.1
+RUN rbenv global 2.4.1
+RUN rbenv rehash
+
+RUN gem install bundler
+
+WORKDIR /data/github-markup
+COPY github-markup.gemspec .
+COPY Gemfile .
+COPY Gemfile.lock .
+COPY lib/github-markup.rb lib/github-markup.rb
+RUN bundle
+
+ENV LC_ALL en_US.UTF-8
+RUN locale-gen en_US.UTF-8
diff --git a/README.md b/README.md
@@ -29,7 +29,8 @@ you wish to run the library. You can also run `script/bootstrap` to fetch them a
 * [.asciidoc, .adoc, .asc](http://asciidoc.org/) -- `gem install asciidoctor` (http://asciidoctor.org)
 * [.pod](http://search.cpan.org/dist/perl/pod/perlpod.pod) -- `Pod::Simple::XHTML`
   comes with Perl >= 5.10. Lower versions should install Pod::Simple from CPAN.
-
+* [.pod6](https://docs.perl6.org/language/pod) -- No additional
+  dependency beyond perl6 `Pod::To::HTML` (in stdlib)
 
 Installation
 -----------
@@ -38,6 +39,14 @@ Installation
 gem install github-markup
 ```
 
+or
+
+```
+bundle install
+```
+
+from this directory.
+
 Usage
 -----
 

diff --git a/github-markup.gemspec b/github-markup.gemspec
@@ -12,6 +12,7 @@ Gem::Specification.new do |s|
   s.license       = "MIT"
 
   s.files         = `git ls-files`.split($\)
+  s.files        += Dir['vendor/Pod-To-HTML/**/*']
   s.executables   = s.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
   s.test_files    = s.files.grep(%r{^(test|spec|features)/})
   s.require_paths = %w[lib]
@@ -23,5 +24,5 @@ Gem::Specification.new do |s|
   s.add_development_dependency 'sanitize', '~> 2.1', '>= 2.1.0'
   s.add_development_dependency 'nokogiri', '~> 1.8.1'
   s.add_development_dependency 'nokogiri-diff', '~> 0.2.0'
-  s.add_development_dependency "github-linguist", "~> 6.0"
+  s.add_development_dependency "github-linguist", ">= 7.1.3"
 end
diff --git a/lib/github/commands/pod62html b/lib/github/commands/pod62html
@@ -0,0 +1,10 @@
+#!/usr/bin/env perl6
+
+use v6;
+use lib $*PROGRAM.IO.parent.add: '../../../vendor/Pod-To-HTML';
+use Pod::To::HTML;
+
+$_ = Pod::To::HTML.render(slurp);
+s:s{\<\!doctype html\>.*\<div id\=\"___top\"\>\<\/div\>\s*} = "";
+s:s{\s*\<\/div\>\s*\<\/body\>\s*\<\/html\>\s*} = "";
+.put;
diff --git a/lib/github/markup.rb b/lib/github/markup.rb
@@ -19,6 +19,7 @@ module Markups
     MARKUP_RDOC = :rdoc
     MARKUP_RST = :rst
     MARKUP_TEXTILE = :textile
+    MARKUP_POD6 = :pod6
   end
 
   module Markup

diff --git a/lib/github/markup/implementation.rb b/lib/github/markup/implementation.rb
@@ -8,7 +8,11 @@ def initialize(regexp, languages)
         @regexp = regexp
 
         if defined?(::Linguist)
-          @languages = languages.map {|l| Linguist::Language[l]}
+          @languages = languages.map do |l|
+            lang = Linguist::Language[l]
+            raise "no match for language #{l.inspect}" if lang.nil?
+            lang
+          end
         end
       end
 

diff --git a/lib/github/markups.rb b/lib/github/markups.rb
@@ -51,4 +51,5 @@
   "restructuredtext"
 )
 
+command(::GitHub::Markups::MARKUP_POD6, :pod62html, /pod6/, ["Pod 6"], "pod6")
 command(::GitHub::Markups::MARKUP_POD, :pod2html, /pod/, ["Pod"], "pod")
diff --git a/test/markup_test.rb b/test/markup_test.rb
@@ -52,7 +52,6 @@ def call
 
     define_method "test_#{markup}" do
       skip "Skipping MediaWiki test because wikicloth is currently not compatible with JRuby." if markup == "mediawiki" && RUBY_PLATFORM == "java"
-
       source = File.read(readme)
       expected_file = "#{readme}.html"
       expected = File.read(expected_file).rstrip
@@ -67,7 +66,6 @@ def call
         f.close_write
         f.read
       end
-
       assert_html_equal expected, actual, <<message
 #{File.basename expected_file}'s contents are not html equal to output:
 #{diff}
@@ -91,7 +89,8 @@ def test_each_render_has_a_name
     assert_equal "wikicloth", GitHub::Markup.renderer('README.wiki', '<h1>Title</h1>').name
     assert_equal "asciidoctor", GitHub::Markup.renderer('README.adoc', '== Title').name
     assert_equal "restructuredtext", GitHub::Markup.renderer('README.rst', 'Title').name
-    assert_equal "pod", GitHub::Markup.renderer('README.pod', '=begin').name
+    assert_equal "pod", GitHub::Markup.renderer('README.pod', '=head1').name
+    assert_equal "pod6", GitHub::Markup.renderer('README.pod6', '=begin pod').name
   end
 
   def test_rendering_by_symbol

diff --git a/test/markups/README.pod6 b/test/markups/README.pod6
@@ -0,0 +1,151 @@
+=begin pod 
+
+=TITLE About the Docs
+
+=SUBTITLE Meta-documentation
+
+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.
+
+An HTML version of the documentation is located online at
+L<https://docs.perl6.org>.
+
+The official source for this documentation is located at L<perl6/doc on
+GitHub|https://github.com/perl6/doc>.
+
+This particular document is a quick overview of the process
+described in more detail in L<CONTRIBUTING on GitHub|https://github.com/perl6/doc/blob/master/CONTRIBUTING.md>.
+This document also provides a short introduction to writing Perl 6
+Pod files, which can be rendered into HTML and other formats.
+
+=head1 Structure
+
+All of the documentation is written in Perl 6 Pod and kept in the C<doc/>
+directory, and the C<doc/Language/> and C<doc/Type/> sub-directories.
+These files are processed as collections of definitions or
+"documentables", which are then post-processed and linked together.
+
+=head1 Generating HTML from Pod
+
+To generate HTML from the Pod files, you'll need:
+
+=item A recent version of the Rakudo Perl 6 compiler
+
+=item The Perl 6 modules Pod::To::HTML, Pod::To::BigPage, and URI::Escape
+(can be installed via L<zef|https://github.com/ugexe/zef>).
+
+=item B<Optional>: L<GraphViz|http://graphviz.org>, for creating graphs
+of the relationships between Perl 6 types
+
+=item B<Optional>: L<Atom Highlights|https://github.com/atom/highlights> and L<language-perl6|https://atom.io/packages/language-perl6>, for syntax
+highlighting
+
+To generate the documentation into the C<html/> folder, run:
+
+=begin code :lang<shell>
+perl6 htmlify.p6
+=end code
+
+To host the documentation from a web server, have Perl 5
+and Mojolicious::Lite installed, then run:
+
+=begin code :lang<shell>
+perl app.pl daemon
+=end code
+
+=head1 Contributing
+
+The documentation is written in Perl 6 Pod.
+
+For a quick introduction to Perl 6 Pod, see L<Perl 6 Pod|https://docs.perl6.org/language/pod>.
+
+For full details about the Perl 6 Pod specification, see L<Synopsis 26, Documentation|https://design.perl6.org/S26.html>.
+
+=head2 Adding definitions
+
+Documentables can be defined using an C<=headN> Pod directive, where
+C<N> is greater than zero (e.g., C<=head1>, C<=head2>, …).
+
+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:
+
+=begin code :allow<R> :skip-test
+=head2 R<My Definition>
+
+Some paragraphs, followed by some code:
+
+    my Code $examples = "amazing";
+
+Mind === blown.
+
+=head3 Minor details about R<My Definition>
+
+It's fantastic.
+
+=head2 And now, for something completely different
+
+…
+
+=end code
+
+The documentable R<My Definition> extends down to the C<=head2 And now…>.
+
+Documentables may contain other documentables. Class documentables, for
+example, often contain the methods the class implements.
+
+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:
+
+=begin code :skip-test
+
+=item X<C<How to use the þ infix> | infix,þ> (This a special case, which
+is always considered a definition)
+
+=item C<The þ Infix>
+
+=item B<The C<þ> Infix>
+
+=item C<Infix þ>
+
+=item B<Infix C<þ>>
+
+=item C<trait is cached> (A special case for the L<trait|/language/functions#Traits> documentables)
+
+=end code
+
+Then the results on the rendered page:
+
+=item X<C<How to use the þ infix> | infix,þ> (This is a special case, which
+is always considered a definition)
+
+=item C<The þ Infix>
+
+=item B<The C<þ> Infix>
+
+=item C<Infix þ>
+
+=item B<Infix C<þ>>
+
+=item C<trait is cached> (A special case for the L<trait|/language/functions#Traits> documentables)
+
+These items should now be searchable by using the search field in the HTML docs.
+
+You can add emphasis with bold (B<V< B<> >>) or italicized (B<V< I<> >>),
+with or without code formatting (B<V< C<> >>).  Due to current parser limitations,
+special steps have to be taken to use B<V< X<> >> with other formatting codes; for example:
+
+=begin code :skip-test
+=item X<B<foo>|foo> a fancy subroutine
+=end code
+
+renders like this
+
+=item X<B<foo>|foo> a fancy subroutine
+
+Notice that text after a pipe ('|') has no formatting. Also note that B<V< C<> >>
+preserves spaces and treats text as verbatim.
+=end pod
+