History

Merge pull request #1395 from scherepn/perl-update

Update Perl documentation

Simon Legner committed 5 years ago

Commit 2c9185b2 parents a525a79 3af0bbe7 files · +134 −80Browse files

Unified · Split

7 files
  1. assets/javascripts/templates/pages/about_tmpl.coffee +1 −1
  2. assets/stylesheets/pages/_perl.scss +5 −1
  3. docs/file-scrapers.md +0 −2
  4. lib/docs/filters/perl/clean_html.rb +8 −36
  5. lib/docs/filters/perl/entries.rb +73 −26
  6. lib/docs/filters/perl/pre_clean_html.rb +17 −0
  7. lib/docs/scrapers/perl.rb +30 −14
assets/javascripts/templates/pages/about_tmpl.coffee+1−1
@@ -578,7 +578,7 @@ credits = [ · 577 unmodified lines
578 'https://raw.githubusercontent.com/pydata/pandas/master/LICENSE'578 'https://raw.githubusercontent.com/pydata/pandas/master/LICENSE'
579 ], [579 ], [
580 'Perl',580 'Perl',
581 '1993-2016 Larry Wall and others',581 '1993-2020 Larry Wall and others',
582 'GPLv1',582 'GPLv1',
583 'https://perldoc.perl.org/index-licence.html'583 'https://perldoc.perl.org/index-licence.html'
584 ], [584 ], [
assets/stylesheets/pages/_perl.scss+5−1
@@ -1,5 +1,9 @@
1._perl {1._perl {
2 @extend %simple;2 @extend %simple;
3 3
4 > h4 { @extend %block-label; }4 dt + dt { margin-top: 1em; }
5
6 > dl > dt { @extend %block-label; }
7 > dl > dt.function { @extend %label-blue; }
8 > dl > dt.variable { @extend %label-green; }
5}9}
docs/file-scrapers.md+0−2
@@ -128,8 +128,6 @@ bsdtar --extract --to-stdout --file openjdk-8-doc_8u272-b10-1_all.deb data.tar.x · 127 unmodified lines
128bsdtar --extract --xz --file - --strip-components=6 --directory=docs/openjdk\~8/ ./usr/share/doc/openjdk-8-jre-headless/api/128bsdtar --extract --xz --file - --strip-components=6 --directory=docs/openjdk\~8/ ./usr/share/doc/openjdk-8-jre-headless/api/
129```129```
130 130
131## Perl
132
133## PHP131## PHP
134 132
135## Python133## Python
lib/docs/filters/perl/clean_html.rb+8−36
@@ -2,49 +2,21 @@ module Docs · 1 unmodified line
2 class Perl2 class Perl
3 class CleanHtmlFilter < Filter3 class CleanHtmlFilter < Filter
4 def call4 def call
5 root_page? ? root : other
6 doc
7 end
8
9 def root
10 doc.inner_html = '<h1>Perl 5 Documentation</h1>'
11 end
12
13 def other
14 @doc = at_css('#content_body')
15
16 css('noscript', '#recent_pages', '#from_search', '#page_index', '.mod_az_list').remove
17
18 css('h1, h2, h3, h4').each do |node|5 css('h1, h2, h3, h4').each do |node|
19 node.name = node.name.sub(/\d/) { |i| i.to_i + 1 }6 node.name = node.name.sub(/\d/) { |i| i.to_i + 1 }
20 end7 end
21 8
22 at_css('h2').name = 'h1'9 css('pre > code').each do |node|
23 10 node.parent['data-language'] = 'perl'
24 css('a[name] + h2', 'a[name] + h3', 'a[name] + h4', 'a[name] + h5').each do |node|
25 node['id'] = node.previous_element['name']
26 end
27
28 css('li > a[name]').each do |node|
29 node.parent['id'] = node['name']
30 end
31
32 css('pre').each do |node|
33 node.css('li').each do |li|
34 li.content = li.content + "\n"
35 end
36 node.content = node.content11 node.content = node.content
37 node.inner_html = node.inner_html.strip_heredoc
38 node['data-language'] = 'perl'
39 end12 end
40 13
41 if slug =~ /functions/ || slug == 'perlvar'14 css('dl > dt').each do |node|
42 css('ul > li[id]').each do |node|15 case slug
43 heading = node.at_css('b')16 when 'perlfunc'
44 heading.name = 'h2'17 node['class'] = 'function'
45 heading['id'] = node['id']18 when 'perlvar'
46 node.parent.before(node.children)19 node['class'] = 'variable'
47 node.remove
48 end20 end
49 end21 end
50 22
lib/docs/filters/perl/entries.rb+73−26
@@ -2,54 +2,101 @@ module Docs · 1 unmodified line
2 class Perl2 class Perl
3 class EntriesFilter < Docs::EntriesFilter3 class EntriesFilter < Docs::EntriesFilter
4 REPLACE_TYPES = {4 REPLACE_TYPES = {
5 'Platform specific' => 'Platform Specific',5 'Platform-Specific' => 'Platform Specific',
6 'Internals and C language interface' => 'Internals',6 'Internals and C Language Interface' => 'Internals',
7 'Tutorials' => 'Manual: Tutorials',
8 'Overview' => 'Manual: Overview'
9 }
10
11 # Individual pages within the Perl documentation are missing all context
12 # for anything even resembling a 'type'. So we're going to grab it
13 # elsewhere with a neat trick: dynamically generate a map from a few
14 # ~index~ pages at runtime which is then referenced on future pages.
15 # Prepopulate w/ edge cases
16 TYPES = {
17 'pod2man' => 'Utilities',
18 'pod2text' => 'Utilities',
19 'encguess' => 'Utilities',
20 'streamzip' => 'Utilities',
21 'pl2pm' => 'Utilities',
7 22
23 'perl' => 'Manual: Overview',
24 'perldoc' => 'Manual: Overview',
25 'perlintro' => 'Manual: Overview',
8 'perlop' => 'Operators',26 'perlop' => 'Operators',
9 'perlvar' => 'Variables',27 'perlvar' => 'Variables',
10 'Functions' => 'Functions'28 'perlref' => 'Reference Manual',
29 'modules' => 'Standard Modules',
30 'perlutil' => 'Utilities',
31
32 'warnings' => 'Pragmas',
33 'strict' => 'Pragmas',
34
35 'Pod::Text::Overstrike' => 'Standard Modules',
36 'Test2::EventFacet::Hub' => 'Standard Modules'
11 }37 }
12 38
13 MANUAL_TYPES = %w(Overview Tutorials FAQs)39 def call
40 case slug
41 when 'perl'
42 css('h2').each do |heading|
43 heading.next_element.css('a').each do |node|
44 TYPES[node.content] = heading.content
45 end
46 end
14 47
15 def breadcrumbs48 when 'modules'
16 @breadcrumbs ||= at_css('#breadcrumbs').content.split('>').each { |s| s.strip! }49 node = at_css('#Pragmatic-Modules')
17 end50 node = node.next_element while node.name != 'ul'
51 node.css('li').each do |n|
52 TYPES[n.at_css('a').content] = 'Pragmas'
53 end
18 54
19 def include_default_entry?55 node = at_css('#Standard-Modules')
20 slug !~ /\Aindex/56 node = node.next_element while node.name != 'ul'
57 node.css('li').each do |n|
58 TYPES[n.at_css('a').content] = 'Standard Modules'
59 end
60
61 when 'perlutil'
62 css('dl > dt').each do |node|
63 TYPES[node['id']] = "Utilities"
64 end
65 end
66
67 super
21 end68 end
22 69
23 def get_name70 def get_name
24 at_css('h1').content.strip71 slug
25 end72 end
26 73
27 def get_type74 def get_type
28 case breadcrumbs[1]75 case slug
29 when 'Language reference'76 when /perl.*faq/
30 REPLACE_TYPES[breadcrumbs[2]] || 'Language'77 'Manual: FAQs'
31 when /\ACore modules/
32 'Core Modules'
33 else78 else
34 type = REPLACE_TYPES[breadcrumbs[1]] || breadcrumbs[1]79 if TYPES.key? name
35 type.prepend 'Manual: ' if MANUAL_TYPES.include?(type)80 REPLACE_TYPES[TYPES[name]] || TYPES[name]
36 type81 else
82 'Other'
83 end
37 end84 end
38 end85 end
39 86
40 def additional_entries87 def additional_entries
41 case slug88 case slug
89 when 'perlfunc'
90 css(':not(p) + dl > dt').each_with_object [] do |node, entries|
91 entries << [node.content, node['id'], 'Functions']
92 end
42 when 'perlop'93 when 'perlop'
43 css('h2').map do |node|94 css('h2').each_with_object [] do |node, entries|
44 name = node.content95 entries << [node.content, node['id'], 'Operators']
45 id = node.previous_element['name']
46 [name, id]
47 end96 end
48 when 'perlvar'97 when 'perlvar'
49 css('#content_body > ul > li > b').map do |node|98 css('> dl > dt').each_with_object [] do |node, entries|
50 name = node.content99 entries << [node.content, node['id'], 'Variables']
51 id = node.previous_element['name']
52 [name, id]
53 end100 end
54 else101 else
55 []102 []
lib/docs/filters/perl/pre_clean_html.rb+17−0
@@ -0,0 +1,17 @@
1module Docs
2 class Perl
3 class PreCleanHtmlFilter < Filter
4 def call
5 css('#links', '.leading-notice', '.permalink').remove
6
7 # Bug somewhere prevents these two ids from loading
8 if slug == 'perlvar'
9 at_css('#\$\"')['id'] = '$ls'
10 at_css('#\$\#')['id'] = '$hash'
11 end
12
13 doc
14 end
15 end
16 end
17end
lib/docs/scrapers/perl.rb+30−14
@@ -1,46 +1,62 @@
1module Docs1module Docs
2 class Perl < FileScraper2 class Perl < UrlScraper
3 self.name = 'Perl'3 self.name = 'Perl'
4 self.type = 'perl'4 self.type = 'perl'
5 self.root_path = 'index.html'5# self.root_path = 'index.html'
6 self.initial_paths = ['modules.html', 'perlutil.html', 'perl.html']
6 self.links = {7 self.links = {
7 home: 'https://www.perl.org/'8 home: 'https://www.perl.org/'
8 }9 }
9 10
10 html_filters.push 'perl/entries', 'perl/clean_html'11 html_filters.push 'perl/pre_clean_html', 'perl/entries', 'perl/clean_html', 'title'
12
13 options[:container] = '#perldocdiv'
11 14
12 options[:skip] = %w(15 options[:skip] = %w(
13 preferences.html16 perlbook perlcommunity perlexperiment perlartistic perlgpl perlhist
14 perlartistic.html17 perlcn perljp perlko perltw
15 perlgpl.html18 perlboot perlbot perlrepository perltodo perltooc perltoot )
16 perlhist.html
17 perltodo.html )
18 19
19 options[:skip_patterns] = [/\.pdf/, /delta\.html/]20 options[:skip_patterns] = [/\Afunctions/, /\Avariables/, /\.pdf/, /delta/]
20 21
21 options[:attribution] = <<-HTML22 options[:attribution] = <<-HTML
22 &copy; 1993&ndash;2016 Larry Wall and others<br>23 &copy; 1993&ndash;2020 Larry Wall and others<br>
23 Licensed under the GNU General Public License version 1 or later, or the Artistic License.<br>24 Licensed under the GNU General Public License version 1 or later, or the Artistic License.<br>
24 The Perl logo is a trademark of the Perl Foundation.25 The Perl logo is a trademark of the Perl Foundation.
25 HTML26 HTML
26 27
28 version '5.32' do
29 self.release = '5.32.0'
30 self.base_url = "https://perldoc.perl.org/#{self.release}/"
31 end
32
33 version '5.30' do
34 self.release = '5.30.3'
35 self.base_url = "https://perldoc.perl.org/#{self.release}/"
36 end
37
38 version '5.28' do
39 self.release = '5.28.3'
40 self.base_url = "https://perldoc.perl.org/#{self.release}/"
41 end
42
27 version '5.26' do43 version '5.26' do
28 self.release = '5.26.0'44 self.release = '5.26.3'
29 self.base_url = "https://perldoc.perl.org/#{self.release}/"45 self.base_url = "https://perldoc.perl.org/#{self.release}/"
30 end46 end
31 47
32 version '5.24' do48 version '5.24' do
33 self.release = '5.24.0'49 self.release = '5.24.4'
34 self.base_url = "https://perldoc.perl.org/#{self.release}/"50 self.base_url = "https://perldoc.perl.org/#{self.release}/"
35 end51 end
36 52
37 version '5.22' do53 version '5.22' do
38 self.release = '5.22.0'54 self.release = '5.22.4'
39 self.base_url = "https://perldoc.perl.org/#{self.release}/"55 self.base_url = "https://perldoc.perl.org/#{self.release}/"
40 end56 end
41 57
42 version '5.20' do58 version '5.20' do
43 self.release = '5.20.2'59 self.release = '5.20.3'
44 self.base_url = "https://perldoc.perl.org/#{self.release}/"60 self.base_url = "https://perldoc.perl.org/#{self.release}/"
45 end61 end
46 62