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

assets/javascripts/templates/pages/about_tmpl.coffee +1 −1
assets/stylesheets/pages/_perl.scss +5 −1
docs/file-scrapers.md +0 −2
lib/docs/filters/perl/clean_html.rb +8 −36
lib/docs/filters/perl/entries.rb +73 −26
lib/docs/filters/perl/pre_clean_html.rb +17 −0
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	578	'https://raw.githubusercontent.com/pydata/pandas/master/LICENSE'
579	579	], [
580	580	'Perl',
581		− '1993-2016 Larry Wall and others',
	581	+ '1993-2020 Larry Wall and others',
582	582	'GPLv1',
583	583	'https://perldoc.perl.org/index-licence.html'
584	584	], [

assets/stylesheets/pages/_perl.scss+5−1

@@ -1,5 +1,9 @@
1	1	._perl {
2	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
128	128	bsdtar --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	131	## PHP
134	132
135	133	## Python

lib/docs/filters/perl/clean_html.rb+8−36

@@ -2,49 +2,21 @@ module Docs · 1 unmodified line
2	2	class Perl
3	3	class CleanHtmlFilter < Filter
4	4	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	5	css('h1, h2, h3, h4').each do \|node\|
19	6	node.name = node.name.sub(/\d/) { \|i\| i.to_i + 1 }
20	7	end
21	8
22		− at_css('h2').name = 'h1'
23		−
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
	9	+ css('pre > code').each do \|node\|
	10	+ node.parent['data-language'] = 'perl'
36	11	node.content = node.content
37		− node.inner_html = node.inner_html.strip_heredoc
38		− node['data-language'] = 'perl'
39	12	end
40	13
41		− if slug =~ /functions/ \|\| slug == 'perlvar'
42		− css('ul > li[id]').each do \|node\|
43		− heading = node.at_css('b')
44		− heading.name = 'h2'
45		− heading['id'] = node['id']
46		− node.parent.before(node.children)
47		− node.remove
	14	+ css('dl > dt').each do \|node\|
	15	+ case slug
	16	+ when 'perlfunc'
	17	+ node['class'] = 'function'
	18	+ when 'perlvar'
	19	+ node['class'] = 'variable'
48	20	end
49	21	end
50	22

lib/docs/filters/perl/entries.rb+73−26

@@ -2,54 +2,101 @@ module Docs · 1 unmodified line
2	2	class Perl
3	3	class EntriesFilter < Docs::EntriesFilter
4	4	REPLACE_TYPES = {
5		− 'Platform specific' => 'Platform Specific',
6		− 'Internals and C language interface' => 'Internals',
	5	+ 'Platform-Specific' => 'Platform Specific',
	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	26	'perlop' => 'Operators',
9	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 breadcrumbs
16		− @breadcrumbs \|\|= at_css('#breadcrumbs').content.split('>').each { \|s\| s.strip! }
17		− end
	48	+ when 'modules'
	49	+ node = at_css('#Pragmatic-Modules')
	50	+ 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?
20		− slug !~ /\Aindex/
	55	+ node = at_css('#Standard-Modules')
	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	68	end
22	69
23	70	def get_name
24		− at_css('h1').content.strip
	71	+ slug
25	72	end
26	73
27	74	def get_type
28		− case breadcrumbs[1]
29		− when 'Language reference'
30		− REPLACE_TYPES[breadcrumbs[2]] \|\| 'Language'
31		− when /\ACore modules/
32		− 'Core Modules'
	75	+ case slug
	76	+ when /perl.*faq/
	77	+ 'Manual: FAQs'
33	78	else
34		− type = REPLACE_TYPES[breadcrumbs[1]] \|\| breadcrumbs[1]
35		− type.prepend 'Manual: ' if MANUAL_TYPES.include?(type)
36		− type
	79	+ if TYPES.key? name
	80	+ REPLACE_TYPES[TYPES[name]] \|\| TYPES[name]
	81	+ else
	82	+ 'Other'
	83	+ end
37	84	end
38	85	end
39	86
40	87	def additional_entries
41	88	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	93	when 'perlop'
43		− css('h2').map do \|node\|
44		− name = node.content
45		− id = node.previous_element['name']
46		− [name, id]
	94	+ css('h2').each_with_object [] do \|node, entries\|
	95	+ entries << [node.content, node['id'], 'Operators']
47	96	end
48	97	when 'perlvar'
49		− css('#content_body > ul > li > b').map do \|node\|
50		− name = node.content
51		− id = node.previous_element['name']
52		− [name, id]
	98	+ css('> dl > dt').each_with_object [] do \|node, entries\|
	99	+ entries << [node.content, node['id'], 'Variables']
53	100	end
54	101	else
55	102	[]

lib/docs/filters/perl/pre_clean_html.rb+17−0

@@ -0,0 +1,17 @@
	1	+module 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
	17	+end

lib/docs/scrapers/perl.rb+30−14

@@ -1,46 +1,62 @@
1	1	module Docs
2		− class Perl < FileScraper
	2	+ class Perl < UrlScraper
3	3	self.name = 'Perl'
4	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	7	self.links = {
7	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	15	options[:skip] = %w(
13		− preferences.html
14		− perlartistic.html
15		− perlgpl.html
16		− perlhist.html
17		− perltodo.html )
	16	+ perlbook perlcommunity perlexperiment perlartistic perlgpl perlhist
	17	+ perlcn perljp perlko perltw
	18	+ perlboot perlbot perlrepository perltodo perltooc perltoot )
18	19
19		− options[:skip_patterns] = [/\.pdf/, /delta\.html/]
	20	+ options[:skip_patterns] = [/\Afunctions/, /\Avariables/, /\.pdf/, /delta/]
20	21
21	22	options[:attribution] = <<-HTML
22		− © 1993–2016 Larry Wall and others<br>
	23	+ © 1993–2020 Larry Wall and others<br>
23	24	Licensed under the GNU General Public License version 1 or later, or the Artistic License.<br>
24	25	The Perl logo is a trademark of the Perl Foundation.
25	26	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	43	version '5.26' do
28		− self.release = '5.26.0'
	44	+ self.release = '5.26.3'
29	45	self.base_url = "https://perldoc.perl.org/#{self.release}/"
30	46	end
31	47
32	48	version '5.24' do
33		− self.release = '5.24.0'
	49	+ self.release = '5.24.4'
34	50	self.base_url = "https://perldoc.perl.org/#{self.release}/"
35	51	end
36	52
37	53	version '5.22' do
38		− self.release = '5.22.0'
	54	+ self.release = '5.22.4'
39	55	self.base_url = "https://perldoc.perl.org/#{self.release}/"
40	56	end
41	57
42	58	version '5.20' do
43		− self.release = '5.20.2'
	59	+ self.release = '5.20.3'
44	60	self.base_url = "https://perldoc.perl.org/#{self.release}/"
45	61	end
46	62