markdown_helper 2.2.0 → 2.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. checksums.yaml +4 -4
  2. data/Gemfile.lock +1 -1
  3. data/README.md +10 -4
  4. data/lib/markdown_helper/version.rb +1 -1
  5. data/lib/markdown_helper.rb +14 -5
  6. data/markdown/readme/README.template.md +8 -3
  7. data/markdown/use_cases/Rakefile +17 -20
  8. data/markdown/use_cases/include_files/diagnose_circular_includes/diagnose_circular_includes.err +9 -9
  9. data/markdown/use_cases/include_files/diagnose_circular_includes/use_case.md +16 -25
  10. data/markdown/use_cases/include_files/diagnose_missing_includee/diagnose_missing_includee.err +9 -9
  11. data/markdown/use_cases/include_files/diagnose_missing_includee/use_case.md +16 -25
  12. data/markdown/use_cases/include_files/include_code_block/use_case.md +7 -17
  13. data/markdown/use_cases/include_files/include_highlighted_code/use_case.md +7 -17
  14. data/markdown/use_cases/include_files/include_markdown/use_case.md +7 -18
  15. data/markdown/use_cases/include_files/include_page_toc/included.md +0 -6
  16. data/markdown/use_cases/include_files/include_page_toc/use_case.md +7 -30
  17. data/markdown/use_cases/include_files/include_text_as_comment/use_case.md +7 -18
  18. data/markdown/use_cases/include_files/include_text_as_details/details.md +5 -0
  19. data/markdown/use_cases/include_files/include_text_as_details/included.md +10 -0
  20. data/markdown/use_cases/include_files/include_text_as_details/includer.md +4 -0
  21. data/markdown/use_cases/include_files/include_text_as_details/use_case.md +84 -0
  22. data/markdown/use_cases/include_files/include_text_as_details/use_case_template.md +31 -0
  23. data/markdown/use_cases/include_files/include_text_as_pre/use_case.md +7 -18
  24. data/markdown/use_cases/include_files/include_with_added_comments/included.md +0 -4
  25. data/markdown/use_cases/include_files/include_with_added_comments/use_case.md +0 -4
  26. data/markdown/use_cases/include_files/interface.md +8 -17
  27. data/markdown/use_cases/include_files/nest_inclusions/use_case.md +7 -16
  28. data/markdown/use_cases/include_files/reuse_text/use_case.md +7 -18
  29. data/markdown/use_cases/use_cases.md +1 -0
  30. metadata +8 -20
  31. data/markdown/use_cases/include_files/diagnose_circular_includes/include.rb +0 -5
  32. data/markdown/use_cases/include_files/diagnose_circular_includes/use_case_builder.rb +0 -64
  33. data/markdown/use_cases/include_files/diagnose_missing_includee/include.rb +0 -5
  34. data/markdown/use_cases/include_files/diagnose_missing_includee/use_case_builder.rb +0 -66
  35. data/markdown/use_cases/include_files/include_code_block/use_case_builder.rb +0 -78
  36. data/markdown/use_cases/include_files/include_generated_text/use_case_builder.rb +0 -37
  37. data/markdown/use_cases/include_files/include_highlighted_code/use_case_builder.rb +0 -82
  38. data/markdown/use_cases/include_files/include_markdown/use_case_builder.rb +0 -80
  39. data/markdown/use_cases/include_files/include_page_toc/use_case_builder.rb +0 -121
  40. data/markdown/use_cases/include_files/include_text_as_comment/use_case_builder.rb +0 -71
  41. data/markdown/use_cases/include_files/include_text_as_pre/use_case_builder.rb +0 -68
  42. data/markdown/use_cases/include_files/include_use_case.rb +0 -104
  43. data/markdown/use_cases/include_files/include_with_added_comments/use_case_builder.rb +0 -66
  44. data/markdown/use_cases/include_files/nest_inclusions/use_case_builder.rb +0 -60
  45. data/markdown/use_cases/include_files/reuse_text/include.rb +0 -5
  46. data/markdown/use_cases/include_files/reuse_text/use_case_builder.rb +0 -48
@@ -1,64 +0,0 @@
1
- require_relative '../include_use_case'
2
-
3
- class DiagnoseCircularIncludes < IncludeUseCase
4
-
5
- def self.build
6
-
7
- use_case = self.new
8
-
9
- use_case.write_ruby_file(pristine = true)
10
-
11
- [
12
- [0, 1],
13
- [1, 2],
14
- [2, 0],
15
- ].each do |indexes|
16
- includer_index, includee_index = *indexes
17
- includer_file_name = "includer_#{includer_index}.md"
18
- includee_file_name = "includer_#{includee_index}.md"
19
- if includer_index == 0
20
- include_description = "@[:markdown](#{includer_file_name})\n"
21
- File.write(INCLUDER_FILE_NAME, include_description)
22
- end
23
- include_description = "@[:markdown](#{includee_file_name})\n"
24
- File.write(includer_file_name, include_description)
25
- end
26
-
27
- File.write(
28
- TEMPLATE_FILE_NAME,
29
- <<EOT
30
- ### Diagnose Circular Includes
31
-
32
- Use the backtrace of inclusions to diagnose and correct circular inclusions: that is inclusions that directly or indirectly cause a file to include itself.
33
-
34
- #### Files To Be Included
35
-
36
- These files demonstrate nested inclusion, with circular inclusions.
37
-
38
- @[markdown](includer_0.md)
39
-
40
- @[markdown](includer_1.md)
41
-
42
- @[markdown](includer_2.md)
43
-
44
- #### Includer File
45
-
46
- This file initiates the nested inclusions.
47
-
48
- @[markdown](#{INCLUDER_FILE_NAME})
49
-
50
- @[:markdown](../interface.md)
51
-
52
- #### Error and Backtrace
53
-
54
- Here's the resulting backtrace of inclusions.
55
-
56
- @[:code_block](diagnose_circular_includes.err)
57
- EOT
58
- )
59
-
60
- use_case.build
61
-
62
- end
63
-
64
- end
@@ -1,5 +0,0 @@
1
- require 'markdown_helper'
2
-
3
- # Option :pristine suppresses comment insertion.
4
- markdown_helper = MarkdownHelper.new(:pristine => true)
5
- markdown_helper.include('includer.md', 'included.md')
@@ -1,66 +0,0 @@
1
- require_relative '../include_use_case'
2
-
3
- class DiagnoseMissingIncludee < IncludeUseCase
4
-
5
- def self.build
6
-
7
- use_case = self.new
8
-
9
- use_case.write_ruby_file(pristine = true)
10
-
11
- [
12
- [0, 1],
13
- [1, 2],
14
- [2, 3],
15
- ].each do |indexes|
16
- includer_index, includee_index = *indexes
17
- includer_file_name = "includer_#{includer_index}.md"
18
- includee_file_name = "includer_#{includee_index}.md"
19
- if includer_index == 0
20
- include_description = "@[:markdown](#{includer_file_name})\n"
21
- File.write(INCLUDER_FILE_NAME, include_description)
22
- end
23
- include_description = "@[:markdown](#{includee_file_name})\n"
24
- File.write(includer_file_name, include_description)
25
- end
26
-
27
- File.write(
28
- TEMPLATE_FILE_NAME,
29
- <<EOT
30
- ### Diagnose Missing Includee
31
-
32
- Use the backtrace of inclusions to diagnose and correct a missing or otherwise unreadable includee file.
33
-
34
- The backtrace is especially useful for errors in nested includes.
35
-
36
- #### Files To Be Included
37
-
38
- These files demonstrate nested inclusion, with a missing includee file.
39
-
40
- @[markdown](includer_0.md)
41
-
42
- @[markdown](includer_1.md)
43
-
44
- @[markdown](includer_2.md)
45
-
46
- #### Includer File
47
-
48
- This file initiates the nested inclusions.
49
-
50
- @[markdown](#{INCLUDER_FILE_NAME})
51
-
52
- @[:markdown](../interface.md)
53
-
54
- #### Error and Backtrace
55
-
56
- Here's the resulting backtrace of inclusions.
57
-
58
- @[:code_block](diagnose_missing_includee.err)
59
- EOT
60
- )
61
-
62
- use_case.build
63
-
64
- end
65
-
66
- end
@@ -1,78 +0,0 @@
1
- require_relative '../include_use_case'
2
-
3
- class IncludeCodeBlock < IncludeUseCase
4
-
5
- def self.build
6
-
7
- use_case = self.new
8
-
9
- includee_file_name = 'hello.rb'
10
-
11
- use_case.files_to_write.store(
12
- includee_file_name,
13
- <<EOT
14
- class HelloWorld
15
- def initialize(name)
16
- @name = name.capitalize
17
- end
18
- def sayHi
19
- puts "Hello #{@name}!"
20
- end
21
- end
22
- EOT
23
- )
24
-
25
- use_case.files_to_write.store(
26
- INCLUDER_FILE_NAME,
27
- <<EOT
28
- This file includes the code as a code block.
29
-
30
- @[:code_block](#{includee_file_name})
31
-
32
- EOT
33
- )
34
-
35
- use_case.files_to_write.store(
36
- TEMPLATE_FILE_NAME,
37
- <<EOT
38
- ### Include Code Block
39
-
40
- Use file inclusion to include text as a code block.
41
-
42
- #### File to Be Included
43
-
44
- Here's a file containing code to be included:
45
-
46
- @[markdown](#{includee_file_name})
47
-
48
- #### Includer File
49
-
50
- Here's a template file that includes it:
51
-
52
- @[markdown](#{INCLUDER_FILE_NAME})
53
-
54
- The treatment token ```:code_block``` specifies that the included text is to be treated as a code block.
55
-
56
- @[:markdown](../interface.md)
57
-
58
- #### File with Inclusion
59
-
60
- Here's the finished file with the included code block:
61
-
62
- @[:pre](#{INCLUDED_FILE_NAME})
63
-
64
- And here's the finished markdown, as rendered on this page:
65
-
66
- ---
67
-
68
- @[:markdown](#{INCLUDED_FILE_NAME})
69
-
70
- ---
71
- EOT
72
- )
73
-
74
- use_case.build
75
-
76
- end
77
-
78
- end
@@ -1,37 +0,0 @@
1
- require_relative '../include_use_case'
2
-
3
- class IncludeGeneratedText < IncludeUseCase
4
-
5
- def self.build
6
-
7
- use_case = self.new
8
-
9
- use_case.files_to_write.store(
10
- TEMPLATE_FILE_NAME,
11
- <<EOT
12
- ### Include Generated Text
13
-
14
- #### Generate Includable Text
15
-
16
- A handy use of file inclusion is seen in including generated text.
17
-
18
- That is, the markdown "build" generates files that are then included in the finished markdown document.
19
-
20
- The use cases documented here take advantage of that. Each use case has an executable Ruby file that has [Here Documents](https://ruby-doc.org/core-2.2.0/doc/syntax/literals_rdoc.html#label-Here+Documents) containing all the relevant text. The build emits the files that are them used to illustrate the use case.
21
-
22
- #### Keeping Example Code "Green"
23
-
24
- An especially handy use of file inclusion is seen in including example code and output.
25
-
26
- 1. Example code in its own file is executed, and its output captured into another file.
27
- 2. Then both are included in markdown that uses the example.
28
-
29
- Running the example each time the markdown is built keeps the example code "green," because it confirms that the code still works.
30
- EOT
31
- )
32
-
33
- use_case.build
34
-
35
- end
36
-
37
- end
@@ -1,82 +0,0 @@
1
- require_relative '../include_use_case'
2
-
3
- class IncludeHighlightedCode < IncludeUseCase
4
-
5
- def self.build
6
-
7
- use_case = self.new
8
-
9
- use_case.write_includer_file
10
-
11
- includee_file_name = 'hello.rb'
12
-
13
- use_case.files_to_write.store(
14
- includee_file_name,
15
- <<EOT
16
- class HelloWorld
17
- def initialize(name)
18
- @name = name.capitalize
19
- end
20
- def sayHi
21
- puts "Hello #{@name}!"
22
- end
23
- end
24
- EOT
25
- )
26
-
27
- use_case.files_to_write.store(
28
- INCLUDER_FILE_NAME,
29
- <<EOT
30
- This file includes the code as highlighted code.
31
-
32
- @[ruby](#{includee_file_name})
33
-
34
- EOT
35
- )
36
-
37
- use_case.files_to_write.store(
38
- TEMPLATE_FILE_NAME,
39
- <<EOT
40
- ### Include Highlighted Code
41
-
42
- Use file inclusion to include text as highlighted code.
43
-
44
- #### File to Be Included
45
-
46
- Here's a file containing Ruby code to be included:
47
-
48
- @[markdown](#{includee_file_name})
49
-
50
- #### Includer File
51
-
52
- Here's a template file that includes it:
53
-
54
- @[markdown](#{INCLUDER_FILE_NAME})
55
-
56
- The treatment token ```ruby``` specifies that the included text is to be highlighted as Ruby code.
57
-
58
- The treatment token can be any Ace mode mentioned in [GitHub Languages](https://github.com/github/linguist/blob/master/lib/linguist/languages.yml). The file lists about 100 Ace modes, covering just about every language and format.
59
-
60
- @[:markdown](../interface.md)
61
-
62
- #### File with Inclusion
63
-
64
- Here's the finished file with the included highlighted code:
65
-
66
- @[:pre](#{INCLUDED_FILE_NAME})
67
-
68
- And here's the finished markdown, as rendered on this page:
69
-
70
- ---
71
-
72
- @[:markdown](#{INCLUDED_FILE_NAME})
73
-
74
- ---
75
- EOT
76
- )
77
-
78
- use_case.build
79
-
80
- end
81
-
82
- end
@@ -1,80 +0,0 @@
1
- require_relative '../include_use_case'
2
-
3
- class IncludeMarkdown < IncludeUseCase
4
-
5
- def self.build
6
-
7
- use_case = self.new
8
-
9
- includee_file_name = 'markdown.md'
10
-
11
- use_case.files_to_write.store(
12
- includee_file_name,
13
- <<EOT
14
- This fiie, to be included, is markdown.
15
-
16
- ### This is a level-three title.
17
-
18
- Here's a [link](http://yahoo.com).
19
-
20
- This is an unordered list:
21
- * One.
22
- * Two.
23
- * Three.
24
- EOT
25
- )
26
-
27
- use_case.files_to_write.store(
28
- INCLUDER_FILE_NAME,
29
- <<EOT
30
- This file includes the markdown file.
31
-
32
- @[:markdown](#{includee_file_name})
33
-
34
- EOT
35
- )
36
-
37
- use_case.files_to_write.store(
38
- TEMPLATE_FILE_NAME,
39
- <<EOT
40
- ### Include Markdown
41
-
42
- Use file inclusion to include markdown. The whole page, includer and includee, will be rendered when it's pushed to GitHub.
43
-
44
- #### File to Be Included
45
-
46
- Here's a file containing markdown to be included:
47
-
48
- @[markdown](#{includee_file_name})
49
-
50
- #### Includer File
51
-
52
- Here's a template file that includes it:
53
-
54
- @[markdown](#{INCLUDER_FILE_NAME})
55
-
56
- The treatment token ```:markdown``` specifies that the included text is to be treated as markdown.
57
-
58
- @[:markdown](../interface.md)
59
-
60
- #### File with Inclusion
61
-
62
- Here's the finished file with the inclusion:
63
-
64
- @[markdown](#{INCLUDED_FILE_NAME})
65
-
66
- And here's the finished markdown, as rendered on this page:
67
-
68
- ---
69
-
70
- @[:markdown](#{includee_file_name})
71
-
72
- ---
73
- EOT
74
- )
75
-
76
- use_case.build
77
-
78
- end
79
-
80
- end
@@ -1,121 +0,0 @@
1
- require_relative '../include_use_case'
2
-
3
- class IncludePageToc < IncludeUseCase
4
-
5
- def self.build
6
-
7
- use_case = self.new
8
-
9
- include_command = IncludeUseCase.construct_include_command(INCLUDER_FILE_NAME, INCLUDED_FILE_NAME, pristine = false)
10
- use_case.commands_to_execute.unshift(include_command)
11
-
12
- includee_0_file_name = 'markdown_0.md'
13
- includee_1_file_name = 'markdown_1.md'
14
-
15
- use_case.files_to_write.store(
16
- includee_0_file_name,
17
- <<EOT
18
-
19
- ## Includee 0 level-two title.
20
-
21
- ### Includee 0 level-three title.
22
-
23
- ### Another includee 0 level-three title.
24
-
25
- ## Another includee 0 level-two title.
26
- EOT
27
- )
28
-
29
- use_case.files_to_write.store(
30
- includee_1_file_name,
31
- <<EOT
32
-
33
- ## Includee 1 level-two title.
34
-
35
- ### Includee 1 level-three title.
36
-
37
- ### Another includee 1 level-three title.
38
-
39
- ## Another includee 1 level-two title.
40
- EOT
41
- )
42
-
43
- use_case.files_to_write.store(
44
- INCLUDER_FILE_NAME,
45
- <<EOT
46
- # Page Title
47
-
48
- @[:page_toc](## Page Contents)
49
-
50
- ## Includer level-two title.
51
-
52
- ### Includer level-three title.
53
-
54
- ### Another includer level-three title.
55
-
56
- ## Another includer level-two title.
57
-
58
- @[:markdown](#{includee_0_file_name})
59
-
60
- @[:markdown](#{includee_1_file_name})
61
-
62
- EOT
63
- )
64
-
65
- use_case.files_to_write.store(
66
- TEMPLATE_FILE_NAME,
67
- <<EOT
68
- ### Include Page TOC
69
-
70
- Use file inclusion to include a page table of contents (page TOC).
71
-
72
- The page TOC is a tree of links:
73
-
74
- - Each link goes to a corresponding markdown title.
75
- - The tree structure reflects the relative depths of the linked headers.
76
-
77
- Below are files to be included and an includer file that will generate the page TOC.
78
-
79
- Note that all file inclusion (even nested inclusions) will be performed before the page TOC is built, so the page TOC covers all the included material.
80
-
81
- #### Files to Be Included
82
-
83
- Here's a file containing markdown to be included:
84
-
85
- @[markdown](#{includee_0_file_name})
86
-
87
- Here's another:
88
-
89
- @[markdown](#{includee_1_file_name})
90
-
91
- #### Includer File
92
-
93
- Here's a template file that includes them:
94
-
95
- @[markdown](#{INCLUDER_FILE_NAME})
96
-
97
- The treatment token ```:page_toc``` specifies where the page TOC is to be inserted.
98
-
99
- @[:markdown](../interface.md)
100
-
101
- #### File with Inclusion
102
-
103
- Here's the finished file with the inclusion:
104
-
105
- @[markdown](#{INCLUDED_FILE_NAME})
106
-
107
- And here's the finished markdown, as rendered on this page:
108
-
109
- ---
110
-
111
- @[:markdown](#{INCLUDED_FILE_NAME})
112
-
113
- ---
114
- EOT
115
- )
116
-
117
- use_case.build
118
-
119
- end
120
-
121
- end
@@ -1,71 +0,0 @@
1
- require_relative '../include_use_case'
2
-
3
- class IncludeTextAsComment < IncludeUseCase
4
-
5
- def self.build
6
-
7
- use_case = self.new
8
-
9
- includee_file_name = 'hello.rb'
10
-
11
- use_case.files_to_write.store(
12
- includee_file_name,
13
- <<EOT
14
- class HelloWorld
15
- def initialize(name)
16
- @name = name.capitalize
17
- end
18
- def sayHi
19
- puts "Hello #{@name}!"
20
- end
21
- end
22
- EOT
23
- )
24
-
25
- use_case.files_to_write.store(
26
- INCLUDER_FILE_NAME,
27
- <<EOT
28
- This file includes the code as a comment.
29
-
30
- @[:comment](#{includee_file_name})
31
-
32
- EOT
33
- )
34
-
35
- use_case.files_to_write.store(
36
- TEMPLATE_FILE_NAME,
37
- <<EOT
38
- ### Include Text As Comment
39
-
40
- Use file inclusion to include text (or even code) as a comment.
41
-
42
- #### File to Be Included
43
-
44
- Here's a file containing code to be included:
45
-
46
- @[markdown](#{includee_file_name})
47
-
48
- #### Includer File
49
-
50
- Here's a template file that includes it:
51
-
52
- @[markdown](#{INCLUDER_FILE_NAME})
53
-
54
- The treatment token ```:comment``` specifies that the included text is to be treated as a comment.
55
-
56
- @[:markdown](../interface.md)
57
-
58
- #### File with Inclusion
59
-
60
- Here's the finished file with the included comment:
61
-
62
- @[markdown](#{INCLUDED_FILE_NAME})
63
-
64
- EOT
65
- )
66
-
67
- use_case.build
68
-
69
- end
70
-
71
- end
@@ -1,68 +0,0 @@
1
- require_relative '../include_use_case'
2
-
3
- class IncludeTextAsPre < IncludeUseCase
4
-
5
- def self.build
6
-
7
- use_case = self.new
8
-
9
- includee_file_name = 'triple_backtick.md'
10
-
11
- use_case.files_to_write.store(
12
- includee_file_name,
13
- <<EOT
14
- This file uses triple-backtick to format a ```symbol```, which means that it cannot be included as a code block.
15
- EOT
16
- )
17
-
18
- use_case.files_to_write.store(
19
- INCLUDER_FILE_NAME,
20
- <<EOT
21
- This file includes the backticked content as pre(formatted).
22
-
23
- @[:pre](#{includee_file_name})
24
-
25
- EOT
26
- )
27
-
28
- use_case.files_to_write.store(
29
- TEMPLATE_FILE_NAME,
30
- <<EOT
31
- ### Include Text As Pre
32
-
33
- Use file inclusion to include text as pre-formatted (rather than as a code block).
34
-
35
- You might need to do this if you have text to include that has triple-backticks.
36
-
37
- #### File to Be Included
38
-
39
- Here's a file containing text to be included; the text has triple-backticks.:
40
-
41
- @[markdown](#{includee_file_name})
42
-
43
- #### Includer File
44
-
45
- Here's a template file that includes it:
46
-
47
- @[markdown](#{INCLUDER_FILE_NAME})
48
-
49
- The treatment token ```:pre``` specifies that the included text is to be treated as pre-formatted.
50
-
51
- @[:markdown](../interface.md)
52
-
53
- #### File with Inclusion
54
-
55
- Here's the finished file with the included preformatted text:
56
-
57
- @[markdown](#{INCLUDED_FILE_NAME})
58
-
59
- EOT
60
- )
61
-
62
- system(INCLUDE_COMMAND)
63
-
64
- use_case.build
65
-
66
- end
67
-
68
- end