markdown_helper 1.7.0 → 1.8.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/Gemfile.lock +1 -1
- data/README.md +7 -7
- data/lib/markdown_helper.rb +19 -12
- data/lib/markdown_helper/version.rb +1 -1
- data/markdown/README.template.md +6 -6
- data/markdown/include.md +1 -1
- data/markdown/use_cases/Rakefile +66 -0
- data/markdown/use_cases/include/include_generated_text/build.rb +46 -0
- data/markdown/use_cases/include/include_with_added_comments/include_with_added_comments.md +37 -0
- data/markdown/use_cases/include/include_with_added_comments/include_with_added_comments.rb +84 -0
- data/markdown/use_cases/include/include_with_added_comments/included.md +5 -0
- data/markdown/use_cases/include/include_with_added_comments/includee.md +1 -0
- data/markdown/use_cases/include/include_with_added_comments/includer.md +1 -0
- data/markdown/use_cases/include/include_with_added_comments/template.md +24 -0
- data/markdown/use_cases/include/reuse_text/included.md +7 -0
- data/markdown/use_cases/include/reuse_text/includer.md +7 -0
- data/markdown/use_cases/include/reuse_text/reusable_text.md +1 -0
- data/markdown/use_cases/include/reuse_text/reuse_text.md +54 -0
- data/markdown/use_cases/include/reuse_text/reuse_text.rb +100 -0
- data/markdown/use_cases/{reuse_text → include/reuse_text}/template.md +8 -6
- data/markdown/use_cases/pristine.md +1 -0
- data/markdown/use_cases/resolve/gemify_images/gemify_images.md +11 -0
- data/markdown/use_cases/resolve/gemify_images/gemify_images.rb +39 -0
- data/markdown/use_cases/resolve/gemify_images/relative_image.md +1 -0
- data/markdown/use_cases/resolve/gemify_images/resolved_image.md +1 -0
- data/markdown/use_cases/{gemify_images → resolve/gemify_images}/template.md +4 -2
- data/markdown/use_cases/{resize_images → resolve/resize_images}/template.md +0 -0
- data/markdown/use_cases/use_cases.md +6 -0
- data/markdown/verbatim_ruby_template.md +1 -1
- metadata +24 -11
- data/markdown/use_cases/reuse_text/included.md +0 -7
- data/markdown/use_cases/reuse_text/includer.md +0 -3
- data/markdown/use_cases/reuse_text/reusable_text.md +0 -1
- data/markdown/use_cases/reuse_text/reuse_text.md +0 -48
- data/markdown/use_cases/reuse_text/reuse_text.rb +0 -69
- data/markdown/use_cases/verify_examples/template.md +0 -14
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA1:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 6b99bdd941c258fc9c48888bcbcbc0c997519e21
|
4
|
+
data.tar.gz: 84ef4845336cd1b747144c9b9ba03610dd240bf8
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: cc670ccec98fecb5020389acba9152a8caf9d03121a6cac264257d31e30c54f32ed446681b2fce867fde7740ae93203c2d294b49016a10e2763580a64f9ecebd
|
7
|
+
data.tar.gz: 798314b57e9add79b6723e07be83fc4ba0115fea3d9710e84d7be71e330b3fd5aee6c09ee040f766b2bba96c749be6935439f1f647f03f991c71cf59d9916cc8
|
data/Gemfile.lock
CHANGED
data/README.md
CHANGED
@@ -12,8 +12,8 @@
|
|
12
12
|
|
13
13
|
Command-line interface is now supported:
|
14
14
|
|
15
|
-
*
|
16
|
-
* ```
|
15
|
+
* Added first [use cases](markdown/use_cases/use_cases.md#use-cases) (there will be more).
|
16
|
+
* Deprecated treatment ```:verbatim```, changing to ```:markdown```. The older term could be confusing, because although text to be treated ```:verbatim``` is included 'verbatim' (without change), it will be processed as GitHub markdown.
|
17
17
|
|
18
18
|
## What's This?
|
19
19
|
|
@@ -87,11 +87,11 @@ end
|
|
87
87
|
|
88
88
|
Comment text is written into the output between the comment delimiters <code>\<!--</code> and <code>--></code>
|
89
89
|
|
90
|
-
####
|
90
|
+
#### Markdown
|
91
91
|
|
92
|
-
|
92
|
+
Markdown text is included unadorned, and will be processed on GitHub as markdown.
|
93
93
|
|
94
|
-
The
|
94
|
+
The markdown text is itself scanned for nested includes.
|
95
95
|
|
96
96
|
### Usage
|
97
97
|
|
@@ -148,7 +148,7 @@ where:
|
|
148
148
|
* *format* (in square brackets) is one of the following:
|
149
149
|
* Highlighting mode such as <code>[ruby]</code>, to include a highlighted code block. This can be any Ace mode mentioned in [GitHub Languages](https://github.com/github/linguist/blob/master/lib/linguist/languages.yml).
|
150
150
|
* <code>[:code_block]</code>, to include a plain code block.
|
151
|
-
* <code>[:
|
151
|
+
* <code>[:markdown]</code>, to include text markdown (to be rendered as markdown).
|
152
152
|
* *relative_file_path* points to the file to be included.
|
153
153
|
|
154
154
|
##### Example Include Descriptions
|
@@ -160,7 +160,7 @@ where:
|
|
160
160
|
|
161
161
|
@[:code_block](my_language.xyzzy)
|
162
162
|
|
163
|
-
@[:
|
163
|
+
@[:markdown](my_markdown.md)
|
164
164
|
```
|
165
165
|
<!-- <<<<<< END INCLUDED FILE (code_block): SOURCE markdown/include.md -->
|
166
166
|
|
data/lib/markdown_helper.rb
CHANGED
@@ -38,11 +38,11 @@ class MarkdownHelper
|
|
38
38
|
# @example pragma to include text as a plain code block.
|
39
39
|
# @[:code_block](foo.xyz)
|
40
40
|
#
|
41
|
-
# @example pragma to include text
|
42
|
-
# @[:
|
41
|
+
# @example pragma to include text markdown, to be rendered as markdown.
|
42
|
+
# @[:markdown](foo.md)
|
43
43
|
def include(template_file_path, markdown_file_path)
|
44
44
|
send(:generate_file, template_file_path, markdown_file_path, __method__) do |input_lines, output_lines|
|
45
|
-
send(:include_files, template_file_path, input_lines, output_lines,
|
45
|
+
send(:include_files, template_file_path, input_lines, output_lines, markdown_inclusions = {})
|
46
46
|
end
|
47
47
|
end
|
48
48
|
|
@@ -106,7 +106,7 @@ class MarkdownHelper
|
|
106
106
|
output
|
107
107
|
end
|
108
108
|
|
109
|
-
def include_files(includer_file_path, input_lines, output_lines,
|
109
|
+
def include_files(includer_file_path, input_lines, output_lines, markdown_inclusions)
|
110
110
|
|
111
111
|
input_lines.each_with_index do |input_line, line_index|
|
112
112
|
match_data = input_line.match(INCLUDE_REGEXP)
|
@@ -119,8 +119,12 @@ class MarkdownHelper
|
|
119
119
|
treatment = case treatment
|
120
120
|
when ':code_block'
|
121
121
|
:code_block
|
122
|
+
when ':markdown'
|
123
|
+
:markdown
|
122
124
|
when ':verbatim'
|
123
|
-
:verbatim
|
125
|
+
message = "Treatment ':verbatim' is deprecated; please use treatment ':markdown'."
|
126
|
+
warn(message)
|
127
|
+
:markdown
|
124
128
|
when ':comment'
|
125
129
|
:comment
|
126
130
|
else
|
@@ -132,12 +136,14 @@ class MarkdownHelper
|
|
132
136
|
relative_included_file_path
|
133
137
|
)
|
134
138
|
included_real_path = new_inclusion.included_real_path
|
135
|
-
if treatment == :
|
136
|
-
previously_included =
|
139
|
+
if treatment == :markdown
|
140
|
+
previously_included = markdown_inclusions.include?(included_real_path)
|
137
141
|
if previously_included
|
138
|
-
|
142
|
+
markdown_inclusions.store(included_real_path, new_inclusion)
|
139
143
|
message_lines = ['Includes are circular:']
|
140
|
-
|
144
|
+
i = 0
|
145
|
+
markdown_inclusions.each_with_index do |path_and_inclusion, i|
|
146
|
+
_, inclusion = *path_and_inclusion
|
141
147
|
message_lines.push(" Level #{i}:")
|
142
148
|
message_lines.push(" Includer: #{inclusion.includer_file_path}:#{inclusion.includer_line_number}")
|
143
149
|
message_lines.push(" Relative file path: #{inclusion.relative_included_file_path}")
|
@@ -147,7 +153,6 @@ class MarkdownHelper
|
|
147
153
|
message = message_lines.join("\n")
|
148
154
|
raise RuntimeError.new(message)
|
149
155
|
end
|
150
|
-
verbatim_inclusions[included_real_path] = new_inclusion
|
151
156
|
end
|
152
157
|
output_lines.push(comment(" >>>>>> BEGIN INCLUDED FILE (#{treatment}): SOURCE #{new_inclusion.included_file_path} ")) unless pristine
|
153
158
|
include_lines = File.readlines(new_inclusion.included_file_path)
|
@@ -156,9 +161,11 @@ class MarkdownHelper
|
|
156
161
|
warn(message)
|
157
162
|
end
|
158
163
|
case treatment
|
159
|
-
when :
|
164
|
+
when :markdown
|
160
165
|
# Pass through unadorned, but honor any nested includes.
|
161
|
-
|
166
|
+
markdown_inclusions.store(included_real_path, new_inclusion)
|
167
|
+
include_files(new_inclusion.included_file_path, include_lines, output_lines, markdown_inclusions)
|
168
|
+
markdown_inclusions.delete(included_real_path)
|
162
169
|
when :comment
|
163
170
|
output_lines.push(comment(include_lines.join('')))
|
164
171
|
else
|
data/markdown/README.template.md
CHANGED
@@ -6,8 +6,8 @@
|
|
6
6
|
|
7
7
|
Command-line interface is now supported:
|
8
8
|
|
9
|
-
*
|
10
|
-
* ```
|
9
|
+
* Added first [use cases](markdown/use_cases/use_cases.md#use-cases) (there will be more).
|
10
|
+
* Deprecated treatment ```:verbatim```, changing to ```:markdown```. The older term could be confusing, because although text to be treated ```:verbatim``` is included 'verbatim' (without change), it will be processed as GitHub markdown.
|
11
11
|
|
12
12
|
## What's This?
|
13
13
|
|
@@ -59,11 +59,11 @@ Use the markdown helper to merge external files into a markdown (</code>.md</cod
|
|
59
59
|
|
60
60
|
Comment text is written into the output between the comment delimiters <code>\<!--</code> and <code>--></code>
|
61
61
|
|
62
|
-
####
|
62
|
+
#### Markdown
|
63
63
|
|
64
|
-
|
64
|
+
Markdown text is included unadorned, and will be processed on GitHub as markdown.
|
65
65
|
|
66
|
-
The
|
66
|
+
The markdown text is itself scanned for nested includes.
|
67
67
|
|
68
68
|
### Usage
|
69
69
|
|
@@ -86,7 +86,7 @@ where:
|
|
86
86
|
* *format* (in square brackets) is one of the following:
|
87
87
|
* Highlighting mode such as <code>[ruby]</code>, to include a highlighted code block. This can be any Ace mode mentioned in [GitHub Languages](https://github.com/github/linguist/blob/master/lib/linguist/languages.yml).
|
88
88
|
* <code>[:code_block]</code>, to include a plain code block.
|
89
|
-
* <code>[:
|
89
|
+
* <code>[:markdown]</code>, to include text markdown (to be rendered as markdown).
|
90
90
|
* *relative_file_path* points to the file to be included.
|
91
91
|
|
92
92
|
##### Example Include Descriptions
|
data/markdown/include.md
CHANGED
@@ -0,0 +1,66 @@
|
|
1
|
+
|
2
|
+
namespace :build do
|
3
|
+
|
4
|
+
desc 'Build use case markdown'
|
5
|
+
task :use_cases do
|
6
|
+
File.open('use_cases.md', 'w') do |use_case_file|
|
7
|
+
use_case_file.puts(<<EOT
|
8
|
+
# Use Cases
|
9
|
+
|
10
|
+
EOT
|
11
|
+
)
|
12
|
+
dir_path = File.dirname(__FILE__)
|
13
|
+
use_case_file_paths = []
|
14
|
+
tbs_file_paths = []
|
15
|
+
Dir.chdir(dir_path) do
|
16
|
+
use_case_dirs = {
|
17
|
+
:include => %w/
|
18
|
+
reuse_text
|
19
|
+
include_with_added_comments
|
20
|
+
/,
|
21
|
+
:resolve => %w/
|
22
|
+
/
|
23
|
+
}
|
24
|
+
use_case_dirs.each_pair do |section, dir_names|
|
25
|
+
use_case_file.puts(<<EOT
|
26
|
+
## #{section.to_s.capitalize}
|
27
|
+
|
28
|
+
EOT
|
29
|
+
) unless dir_names.empty?
|
30
|
+
dir_names.each do |dir_name|
|
31
|
+
ruby_file_path = File.join(
|
32
|
+
dir_path,
|
33
|
+
section.to_s,
|
34
|
+
dir_name,
|
35
|
+
"#{dir_name}.rb"
|
36
|
+
)
|
37
|
+
if File.exist?(ruby_file_path)
|
38
|
+
command = "ruby #{ruby_file_path}"
|
39
|
+
system(command)
|
40
|
+
end
|
41
|
+
use_case_file_path = File.join(
|
42
|
+
dir_path,
|
43
|
+
section.to_s,
|
44
|
+
dir_name,
|
45
|
+
"#{dir_name}.md"
|
46
|
+
)
|
47
|
+
if File.exist?(use_case_file_path)
|
48
|
+
title_line = File.open(use_case_file_path).grep(/^#/).first.chomp
|
49
|
+
title = title_line.split(/\s/, 2).pop
|
50
|
+
use_case_file_name = File.basename(use_case_file_path)
|
51
|
+
use_case_name = File.basename(use_case_file_path, '.md')
|
52
|
+
use_case_anchor = use_case_name.gsub('_', '-')
|
53
|
+
use_case_relative_url = File.join(
|
54
|
+
section.to_s,
|
55
|
+
dir_name,
|
56
|
+
use_case_file_name + '#' + use_case_anchor,
|
57
|
+
)
|
58
|
+
use_case_file.puts("* [#{title}](#{use_case_relative_url})")
|
59
|
+
end
|
60
|
+
end
|
61
|
+
end
|
62
|
+
end
|
63
|
+
end
|
64
|
+
end
|
65
|
+
|
66
|
+
end
|
@@ -0,0 +1,46 @@
|
|
1
|
+
template_file_name = 'template.md'
|
2
|
+
use_case_file_name = 'use_case.md'
|
3
|
+
|
4
|
+
help_text_file_name = 'include_help.txt'
|
5
|
+
includer_file_name = 'includer.md'
|
6
|
+
included_file_name = 'included.md'
|
7
|
+
|
8
|
+
help_command = "markdown_helper include --help > #{help_text_file_name}"
|
9
|
+
include_command = 'markdown_helper include --pristine including_file.md include_help.txt'
|
10
|
+
include_command = "markdown_helper include --pristine #{includer_file_name} #{included_file_name}"
|
11
|
+
build_command = "markdown_helper include --pristine #{template_file_name} #{use_case_file_name}"
|
12
|
+
build_command = "markdown_helper include --pristine #{template_file_name} #{use_case_file_name}"
|
13
|
+
|
14
|
+
|
15
|
+
|
16
|
+
template = <<EOT
|
17
|
+
### Include Generated Text
|
18
|
+
|
19
|
+
Use the markdown helper to include text that is generated at project "build time."
|
20
|
+
|
21
|
+
#### Example
|
22
|
+
|
23
|
+
In this project, some markdown pages include help text from the project's executables. At project "build" time, each executable is run with option ```--help```, and the help text is captured in a file. That file is then included wherever it's needed.
|
24
|
+
|
25
|
+
Thus the displayed help text is always up-to-date.
|
26
|
+
|
27
|
+
### Command to Generate Help Text
|
28
|
+
|
29
|
+
```sh
|
30
|
+
#{help_command}
|
31
|
+
```
|
32
|
+
|
33
|
+
### Help Text
|
34
|
+
|
35
|
+
@[:code_block](#{help_text_file_path})
|
36
|
+
|
37
|
+
###
|
38
|
+
|
39
|
+
EOT
|
40
|
+
|
41
|
+
includer_file = <<EOT
|
42
|
+
### File to Include Help
|
43
|
+
|
44
|
+
@[:code_block](including_file.md)
|
45
|
+
EOT
|
46
|
+
|
@@ -0,0 +1,37 @@
|
|
1
|
+
### Include with Added Comments
|
2
|
+
|
3
|
+
By default (that is, without option ```--pristine```) file inclusion adds comments that:
|
4
|
+
|
5
|
+
* Identify the includer file.
|
6
|
+
* Identify each includee file.
|
7
|
+
|
8
|
+
#### Includee File
|
9
|
+
|
10
|
+
<code>includee.md</code>
|
11
|
+
```markdown
|
12
|
+
Text to be included.
|
13
|
+
```
|
14
|
+
|
15
|
+
#### Includer File
|
16
|
+
|
17
|
+
<code>includer.md</code>
|
18
|
+
```markdown
|
19
|
+
@[:markdown](includee.md)
|
20
|
+
```
|
21
|
+
|
22
|
+
#### Inclusion Command
|
23
|
+
|
24
|
+
```sh
|
25
|
+
markdown_helper include includer.md included.md
|
26
|
+
```
|
27
|
+
|
28
|
+
#### File with Inclusion and Added Comments
|
29
|
+
|
30
|
+
<code>included.md</code>
|
31
|
+
```markdown
|
32
|
+
<!-- >>>>>> BEGIN GENERATED FILE (include): SOURCE includer.md -->
|
33
|
+
<!-- >>>>>> BEGIN INCLUDED FILE (markdown): SOURCE ./includee.md -->
|
34
|
+
Text to be included.
|
35
|
+
<!-- <<<<<< END INCLUDED FILE (markdown): SOURCE ./includee.md -->
|
36
|
+
<!-- <<<<<< END GENERATED FILE (include): SOURCE includer.md -->
|
37
|
+
```
|
@@ -0,0 +1,84 @@
|
|
1
|
+
#!/usr/bin/env ruby
|
2
|
+
|
3
|
+
use_case_dir_path = File.absolute_path(File.dirname(__FILE__))
|
4
|
+
|
5
|
+
includee_file_name = 'includee.md'
|
6
|
+
includee_file_path = File.join(
|
7
|
+
use_case_dir_path,
|
8
|
+
includee_file_name,
|
9
|
+
)
|
10
|
+
|
11
|
+
includer_file_name = 'includer.md'
|
12
|
+
includer_file_path = File.join(
|
13
|
+
use_case_dir_path,
|
14
|
+
includer_file_name,
|
15
|
+
)
|
16
|
+
|
17
|
+
included_file_name = 'included.md'
|
18
|
+
|
19
|
+
use_case_file_name = 'include_with_added_comments.md'
|
20
|
+
use_case_file_path = File.join(
|
21
|
+
use_case_dir_path,
|
22
|
+
use_case_file_name,
|
23
|
+
)
|
24
|
+
|
25
|
+
template_file_name = 'template.md'
|
26
|
+
template_file_path = File.join(
|
27
|
+
use_case_dir_path,
|
28
|
+
template_file_name,
|
29
|
+
)
|
30
|
+
|
31
|
+
include_command = "markdown_helper include #{includer_file_name} #{included_file_name}"
|
32
|
+
|
33
|
+
File.write(
|
34
|
+
includee_file_path,
|
35
|
+
<<EOT
|
36
|
+
Text to be included.
|
37
|
+
EOT
|
38
|
+
)
|
39
|
+
|
40
|
+
File.write(
|
41
|
+
includer_file_path,
|
42
|
+
<<EOT
|
43
|
+
@[:markdown](#{includee_file_name})
|
44
|
+
EOT
|
45
|
+
)
|
46
|
+
|
47
|
+
# Example inclusion.
|
48
|
+
Dir.chdir(use_case_dir_path) do
|
49
|
+
system(include_command)
|
50
|
+
end
|
51
|
+
|
52
|
+
File.write(
|
53
|
+
template_file_path,
|
54
|
+
<<EOT
|
55
|
+
### Include with Added Comments
|
56
|
+
|
57
|
+
By default (that is, without option ```--pristine```) file inclusion adds comments that:
|
58
|
+
|
59
|
+
* Identify the includer file.
|
60
|
+
* Identify each includee file.
|
61
|
+
|
62
|
+
#### Includee File
|
63
|
+
|
64
|
+
@[markdown](#{includee_file_name})
|
65
|
+
|
66
|
+
#### Includer File
|
67
|
+
|
68
|
+
@[markdown](#{includer_file_name})
|
69
|
+
|
70
|
+
#### Inclusion Command
|
71
|
+
|
72
|
+
```sh
|
73
|
+
#{include_command}
|
74
|
+
```
|
75
|
+
|
76
|
+
#### File with Inclusion and Added Comments
|
77
|
+
|
78
|
+
@[markdown](#{included_file_name})
|
79
|
+
EOT
|
80
|
+
)
|
81
|
+
|
82
|
+
# Build use case.
|
83
|
+
build_command = "markdown_helper include --pristine #{template_file_path} #{use_case_file_path}"
|
84
|
+
system(build_command)
|
@@ -0,0 +1,5 @@
|
|
1
|
+
<!-- >>>>>> BEGIN GENERATED FILE (include): SOURCE includer.md -->
|
2
|
+
<!-- >>>>>> BEGIN INCLUDED FILE (markdown): SOURCE ./includee.md -->
|
3
|
+
Text to be included.
|
4
|
+
<!-- <<<<<< END INCLUDED FILE (markdown): SOURCE ./includee.md -->
|
5
|
+
<!-- <<<<<< END GENERATED FILE (include): SOURCE includer.md -->
|
@@ -0,0 +1 @@
|
|
1
|
+
Text to be included.
|
@@ -0,0 +1 @@
|
|
1
|
+
@[:markdown](includee.md)
|
@@ -0,0 +1,24 @@
|
|
1
|
+
### Include with Added Comments
|
2
|
+
|
3
|
+
By default (that is, without option ```--pristine```) file inclusion adds comments that:
|
4
|
+
|
5
|
+
* Identify the includer file.
|
6
|
+
* Identify each includee file.
|
7
|
+
|
8
|
+
#### Includee File
|
9
|
+
|
10
|
+
@[markdown](includee.md)
|
11
|
+
|
12
|
+
#### Includer File
|
13
|
+
|
14
|
+
@[markdown](includer.md)
|
15
|
+
|
16
|
+
#### Inclusion Command
|
17
|
+
|
18
|
+
```sh
|
19
|
+
markdown_helper include includer.md included.md
|
20
|
+
```
|
21
|
+
|
22
|
+
#### File with Inclusion and Added Comments
|
23
|
+
|
24
|
+
@[markdown](included.md)
|
@@ -0,0 +1,7 @@
|
|
1
|
+
This file includes the useful text.
|
2
|
+
|
3
|
+
This is some reusable text that can be included in more than one place (actually, in more than one file).
|
4
|
+
|
5
|
+
Then includes it again.
|
6
|
+
|
7
|
+
This is some reusable text that can be included in more than one place (actually, in more than one file).
|
@@ -0,0 +1 @@
|
|
1
|
+
This is some reusable text that can be included in more than one place (actually, in more than one file).
|
@@ -0,0 +1,54 @@
|
|
1
|
+
### Reuse Text
|
2
|
+
|
3
|
+
Use file inclusion to stay DRY (Don't Repeat Yourself).
|
4
|
+
|
5
|
+
Maintain reusable text in a separate file, then include it wherever it's needed.
|
6
|
+
|
7
|
+
#### File to Be Included
|
8
|
+
|
9
|
+
Here's a file containing some text that can be included:
|
10
|
+
|
11
|
+
<code>reusable_text.md</code>
|
12
|
+
```markdown
|
13
|
+
This is some reusable text that can be included in more than one place (actually, in more than one file).
|
14
|
+
```
|
15
|
+
|
16
|
+
#### Includer File
|
17
|
+
|
18
|
+
Here's a template file that includes it:
|
19
|
+
|
20
|
+
<code>includer.md</code>
|
21
|
+
```markdown
|
22
|
+
This file includes the useful text.
|
23
|
+
|
24
|
+
@[:markdown](reusable_text.md)
|
25
|
+
|
26
|
+
Then includes it again.
|
27
|
+
|
28
|
+
@[:markdown](reusable_text.md)
|
29
|
+
```
|
30
|
+
|
31
|
+
#### Command
|
32
|
+
|
33
|
+
Here's the command to perform the inclusion:
|
34
|
+
|
35
|
+
```sh
|
36
|
+
markdown_helper include --pristine includer.md included.md
|
37
|
+
```
|
38
|
+
|
39
|
+
(Option ```--pristine``` suppresses comment insertion.)
|
40
|
+
|
41
|
+
#### File with Inclusion
|
42
|
+
|
43
|
+
Here's the finished file with the inclusion:
|
44
|
+
|
45
|
+
<code>included.md</code>
|
46
|
+
```markdown
|
47
|
+
This file includes the useful text.
|
48
|
+
|
49
|
+
This is some reusable text that can be included in more than one place (actually, in more than one file).
|
50
|
+
|
51
|
+
Then includes it again.
|
52
|
+
|
53
|
+
This is some reusable text that can be included in more than one place (actually, in more than one file).
|
54
|
+
```
|
@@ -0,0 +1,100 @@
|
|
1
|
+
#!/usr/bin/env ruby
|
2
|
+
|
3
|
+
use_case_dir_path = File.absolute_path(File.dirname(__FILE__))
|
4
|
+
|
5
|
+
reusable_text_file_name = 'reusable_text.md'
|
6
|
+
reusable_text_file_path = File.join(
|
7
|
+
use_case_dir_path,
|
8
|
+
reusable_text_file_name,
|
9
|
+
)
|
10
|
+
|
11
|
+
includer_file_name = 'includer.md'
|
12
|
+
includer_file_path = File.join(
|
13
|
+
use_case_dir_path,
|
14
|
+
includer_file_name,
|
15
|
+
)
|
16
|
+
|
17
|
+
included_file_name = 'included.md'
|
18
|
+
|
19
|
+
use_case_file_name = 'reuse_text.md'
|
20
|
+
use_case_file_path = File.join(
|
21
|
+
use_case_dir_path,
|
22
|
+
use_case_file_name,
|
23
|
+
)
|
24
|
+
|
25
|
+
template_file_name = 'template.md'
|
26
|
+
template_file_path = File.join(
|
27
|
+
use_case_dir_path,
|
28
|
+
template_file_name,
|
29
|
+
)
|
30
|
+
|
31
|
+
include_command = "markdown_helper include --pristine #{includer_file_name} #{included_file_name}"
|
32
|
+
|
33
|
+
File.write(
|
34
|
+
reusable_text_file_path,
|
35
|
+
<<EOT
|
36
|
+
This is some reusable text that can be included in more than one place (actually, in more than one file).
|
37
|
+
EOT
|
38
|
+
)
|
39
|
+
|
40
|
+
|
41
|
+
File.write(
|
42
|
+
includer_file_path,
|
43
|
+
<<EOT
|
44
|
+
This file includes the useful text.
|
45
|
+
|
46
|
+
@[:markdown](#{reusable_text_file_name})
|
47
|
+
|
48
|
+
Then includes it again.
|
49
|
+
|
50
|
+
@[:markdown](#{reusable_text_file_name})
|
51
|
+
EOT
|
52
|
+
)
|
53
|
+
|
54
|
+
# Example inclusion.
|
55
|
+
Dir.chdir(use_case_dir_path) do
|
56
|
+
system(include_command)
|
57
|
+
end
|
58
|
+
|
59
|
+
File.write(
|
60
|
+
template_file_path,
|
61
|
+
<<EOT
|
62
|
+
### Reuse Text
|
63
|
+
|
64
|
+
Use file inclusion to stay DRY (Don't Repeat Yourself).
|
65
|
+
|
66
|
+
Maintain reusable text in a separate file, then include it wherever it's needed.
|
67
|
+
|
68
|
+
#### File to Be Included
|
69
|
+
|
70
|
+
Here's a file containing some text that can be included:
|
71
|
+
|
72
|
+
@[markdown](#{reusable_text_file_name})
|
73
|
+
|
74
|
+
#### Includer File
|
75
|
+
|
76
|
+
Here's a template file that includes it:
|
77
|
+
|
78
|
+
@[markdown](#{includer_file_name})
|
79
|
+
|
80
|
+
#### Command
|
81
|
+
|
82
|
+
Here's the command to perform the inclusion:
|
83
|
+
|
84
|
+
```sh
|
85
|
+
#{include_command}
|
86
|
+
```
|
87
|
+
|
88
|
+
@[:markdown](../../pristine.md)
|
89
|
+
|
90
|
+
#### File with Inclusion
|
91
|
+
|
92
|
+
Here's the finished file with the inclusion:
|
93
|
+
|
94
|
+
@[markdown](#{included_file_name})
|
95
|
+
EOT
|
96
|
+
)
|
97
|
+
|
98
|
+
# Build use case.
|
99
|
+
build_command = "markdown_helper include --pristine #{template_file_path} #{use_case_file_path}"
|
100
|
+
system(build_command)
|
@@ -1,4 +1,4 @@
|
|
1
|
-
###
|
1
|
+
### Reuse Text
|
2
2
|
|
3
3
|
Use file inclusion to stay DRY (Don't Repeat Yourself).
|
4
4
|
|
@@ -8,24 +8,26 @@ Maintain reusable text in a separate file, then include it wherever it's needed.
|
|
8
8
|
|
9
9
|
Here's a file containing some text that can be included:
|
10
10
|
|
11
|
-
@[
|
11
|
+
@[markdown](reusable_text.md)
|
12
12
|
|
13
13
|
#### Includer File
|
14
14
|
|
15
15
|
Here's a template file that includes it:
|
16
16
|
|
17
|
-
@[
|
17
|
+
@[markdown](includer.md)
|
18
18
|
|
19
19
|
#### Command
|
20
20
|
|
21
|
-
Here's the command to perform the inclusion
|
21
|
+
Here's the command to perform the inclusion:
|
22
22
|
|
23
23
|
```sh
|
24
|
-
markdown_helper include includer.md included.md
|
24
|
+
markdown_helper include --pristine includer.md included.md
|
25
25
|
```
|
26
26
|
|
27
|
+
@[:markdown](../../pristine.md)
|
28
|
+
|
27
29
|
#### File with Inclusion
|
28
30
|
|
29
31
|
Here's the finished file with the inclusion:
|
30
32
|
|
31
|
-
@[
|
33
|
+
@[markdown](included.md)
|
@@ -0,0 +1 @@
|
|
1
|
+
(Option ```--pristine``` suppresses comment insertion.)
|
@@ -0,0 +1,11 @@
|
|
1
|
+
### Gemify Images
|
2
|
+
|
3
|
+
Use the markdown helper to resolve image paths for a Ruby gem.
|
4
|
+
|
5
|
+
When you release your GitHub project to gem at RubyGems.org, the documentation is rebuilt into files on RubyDoc.info. When YARD performs this rebuilding, it does some directory restructuring.
|
6
|
+
|
7
|
+
If a markdown file contains an image description that has a relative file path, that path will not be valid in the documentation on RubyDoc.info, and the image will not display in the documentation.
|
8
|
+
|
9
|
+
To avoid that error, use the markdown helper to resolve the relative path to an absolute path.
|
10
|
+
|
11
|
+
This new absolute path points to a file that's automatically maintained in the GitHub project. For that reason,
|
@@ -0,0 +1,39 @@
|
|
1
|
+
#!/usr/bin/env ruby
|
2
|
+
|
3
|
+
relative_image_file_name = 'relative_image.md'
|
4
|
+
absolute_image_file_name = 'resolved_image.md'
|
5
|
+
template_file_name = 'template.md'
|
6
|
+
use_case_file_name = 'gemify_images.md'
|
7
|
+
|
8
|
+
resolve_command = "markdown_helper resolve --pristine #{relative_image_file_name} #{absolute_image_file_name}"
|
9
|
+
|
10
|
+
File.write(
|
11
|
+
relative_image_file_name,
|
12
|
+
<<EOT
|
13
|
+
![html_image](../../../images/html.png)
|
14
|
+
EOT
|
15
|
+
)
|
16
|
+
|
17
|
+
# Example resolution.
|
18
|
+
system(resolve_command)
|
19
|
+
|
20
|
+
File.write(
|
21
|
+
template_file_name,
|
22
|
+
<<EOT
|
23
|
+
### Gemify Images
|
24
|
+
|
25
|
+
Use the markdown helper to resolve image paths for a Ruby gem.
|
26
|
+
|
27
|
+
When you release your GitHub project to gem at RubyGems.org, the documentation is rebuilt into files on RubyDoc.info. When YARD performs this rebuilding, it does some directory restructuring.
|
28
|
+
|
29
|
+
If a markdown file contains an image description that has a relative file path, that path will not be valid in the documentation on RubyDoc.info, and the image will not display in the documentation.
|
30
|
+
|
31
|
+
To avoid that error, use the markdown helper to resolve the relative path to an absolute path.
|
32
|
+
|
33
|
+
This new absolute path points to a file that's automatically maintained in the GitHub project. For that reason,
|
34
|
+
EOT
|
35
|
+
)
|
36
|
+
|
37
|
+
# Build use case.
|
38
|
+
build_command = "markdown_helper include --pristine #{template_file_name} #{use_case_file_name}"
|
39
|
+
system(build_command)
|
@@ -0,0 +1 @@
|
|
1
|
+
![html_image](../../../images/html.png)
|
@@ -0,0 +1 @@
|
|
1
|
+
<img src="" alt="html_image">
|
@@ -1,4 +1,4 @@
|
|
1
|
-
###
|
1
|
+
### Gemify Images
|
2
2
|
|
3
3
|
Use the markdown helper to resolve image paths for a Ruby gem.
|
4
4
|
|
@@ -6,4 +6,6 @@ When you release your GitHub project to gem at RubyGems.org, the documentation
|
|
6
6
|
|
7
7
|
If a markdown file contains an image description that has a relative file path, that path will not be valid in the documentation on RubyDoc.info, and the image will not display in the documentation.
|
8
8
|
|
9
|
-
To avoid that error, use the markdown helper to resolve the relative path to an absolute path.
|
9
|
+
To avoid that error, use the markdown helper to resolve the relative path to an absolute path.
|
10
|
+
|
11
|
+
This new absolute path points to a file that's automatically maintained in the GitHub project. For that reason,
|
File without changes
|
@@ -1 +1 @@
|
|
1
|
-
@[:
|
1
|
+
@[:markdown](include.rb)
|
metadata
CHANGED
@@ -1,14 +1,14 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: markdown_helper
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 1.
|
4
|
+
version: 1.8.0
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- burdettelamar
|
8
8
|
autorequire:
|
9
9
|
bindir: bin
|
10
10
|
cert_chain: []
|
11
|
-
date: 2018-04-
|
11
|
+
date: 2018-04-29 00:00:00.000000000 Z
|
12
12
|
dependencies:
|
13
13
|
- !ruby/object:Gem::Dependency
|
14
14
|
name: bundler
|
@@ -112,15 +112,28 @@ files:
|
|
112
112
|
- markdown/include_usage.rb
|
113
113
|
- markdown/resolve.md
|
114
114
|
- markdown/resolve_usage.rb
|
115
|
-
- markdown/use_cases/
|
116
|
-
- markdown/use_cases/
|
117
|
-
- markdown/use_cases/
|
118
|
-
- markdown/use_cases/
|
119
|
-
- markdown/use_cases/
|
120
|
-
- markdown/use_cases/
|
121
|
-
- markdown/use_cases/
|
122
|
-
- markdown/use_cases/
|
123
|
-
- markdown/use_cases/
|
115
|
+
- markdown/use_cases/Rakefile
|
116
|
+
- markdown/use_cases/include/include_generated_text/build.rb
|
117
|
+
- markdown/use_cases/include/include_with_added_comments/include_with_added_comments.md
|
118
|
+
- markdown/use_cases/include/include_with_added_comments/include_with_added_comments.rb
|
119
|
+
- markdown/use_cases/include/include_with_added_comments/included.md
|
120
|
+
- markdown/use_cases/include/include_with_added_comments/includee.md
|
121
|
+
- markdown/use_cases/include/include_with_added_comments/includer.md
|
122
|
+
- markdown/use_cases/include/include_with_added_comments/template.md
|
123
|
+
- markdown/use_cases/include/reuse_text/included.md
|
124
|
+
- markdown/use_cases/include/reuse_text/includer.md
|
125
|
+
- markdown/use_cases/include/reuse_text/reusable_text.md
|
126
|
+
- markdown/use_cases/include/reuse_text/reuse_text.md
|
127
|
+
- markdown/use_cases/include/reuse_text/reuse_text.rb
|
128
|
+
- markdown/use_cases/include/reuse_text/template.md
|
129
|
+
- markdown/use_cases/pristine.md
|
130
|
+
- markdown/use_cases/resolve/gemify_images/gemify_images.md
|
131
|
+
- markdown/use_cases/resolve/gemify_images/gemify_images.rb
|
132
|
+
- markdown/use_cases/resolve/gemify_images/relative_image.md
|
133
|
+
- markdown/use_cases/resolve/gemify_images/resolved_image.md
|
134
|
+
- markdown/use_cases/resolve/gemify_images/template.md
|
135
|
+
- markdown/use_cases/resolve/resize_images/template.md
|
136
|
+
- markdown/use_cases/use_cases.md
|
124
137
|
- markdown/verbatim_ruby_template.md
|
125
138
|
- markdown_helper.gemspec
|
126
139
|
homepage: https://github.com/BurdetteLamar/markdown_helper
|
@@ -1,7 +0,0 @@
|
|
1
|
-
<!-- >>>>>> BEGIN GENERATED FILE (include): SOURCE includer.md -->
|
2
|
-
This file includes the useful text.
|
3
|
-
|
4
|
-
<!-- >>>>>> BEGIN INCLUDED FILE (verbatim): SOURCE ./reusable_text.md -->
|
5
|
-
This is some useful text that can be included in more than one place (actually, in more than one file).
|
6
|
-
<!-- <<<<<< END INCLUDED FILE (verbatim): SOURCE ./reusable_text.md -->
|
7
|
-
<!-- <<<<<< END GENERATED FILE (include): SOURCE includer.md -->
|
@@ -1 +0,0 @@
|
|
1
|
-
This is some useful text that can be included in more than one place (actually, in more than one file).
|
@@ -1,48 +0,0 @@
|
|
1
|
-
### Use Case: Reuse Text
|
2
|
-
|
3
|
-
Use file inclusion to stay DRY (Don't Repeat Yourself).
|
4
|
-
|
5
|
-
Maintain reusable text in a separate file, then include it wherever it's needed.
|
6
|
-
|
7
|
-
#### File to Be Included
|
8
|
-
|
9
|
-
Here's a file containing some text that can be included:
|
10
|
-
|
11
|
-
<code>reusable_text.md</code>
|
12
|
-
```
|
13
|
-
This is some useful text that can be included in more than one place (actually, in more than one file).
|
14
|
-
```
|
15
|
-
|
16
|
-
#### Includer File
|
17
|
-
|
18
|
-
Here's a template file that includes it:
|
19
|
-
|
20
|
-
<code>includer.md</code>
|
21
|
-
```
|
22
|
-
This file includes the useful text.
|
23
|
-
|
24
|
-
@[:verbatim](reusable_text.md)
|
25
|
-
```
|
26
|
-
|
27
|
-
#### Command
|
28
|
-
|
29
|
-
Here's the command to perform the inclusion (```--pristine``` suppresses inclusion comments):
|
30
|
-
|
31
|
-
```sh
|
32
|
-
markdown_helper include includer.md included.md
|
33
|
-
```
|
34
|
-
|
35
|
-
#### File with Inclusion
|
36
|
-
|
37
|
-
Here's the finished file with the inclusion:
|
38
|
-
|
39
|
-
<code>included.md</code>
|
40
|
-
```
|
41
|
-
<!-- >>>>>> BEGIN GENERATED FILE (include): SOURCE includer.md -->
|
42
|
-
This file includes the useful text.
|
43
|
-
|
44
|
-
<!-- >>>>>> BEGIN INCLUDED FILE (verbatim): SOURCE ./reusable_text.md -->
|
45
|
-
This is some useful text that can be included in more than one place (actually, in more than one file).
|
46
|
-
<!-- <<<<<< END INCLUDED FILE (verbatim): SOURCE ./reusable_text.md -->
|
47
|
-
<!-- <<<<<< END GENERATED FILE (include): SOURCE includer.md -->
|
48
|
-
```
|
@@ -1,69 +0,0 @@
|
|
1
|
-
#!/usr/bin/env ruby
|
2
|
-
|
3
|
-
reusable_text_file_name = 'reusable_text.md'
|
4
|
-
includer_file_name = 'includer.md'
|
5
|
-
included_file_name = 'included.md'
|
6
|
-
use_case_file_name = 'reuse_text.md'
|
7
|
-
template_file_name = 'template.md'
|
8
|
-
|
9
|
-
include_command = "markdown_helper include #{includer_file_name} #{included_file_name}"
|
10
|
-
|
11
|
-
File.write(
|
12
|
-
reusable_text_file_name,
|
13
|
-
<<EOT
|
14
|
-
This is some useful text that can be included in more than one place (actually, in more than one file).
|
15
|
-
EOT
|
16
|
-
)
|
17
|
-
|
18
|
-
File.write(
|
19
|
-
includer_file_name,
|
20
|
-
<<EOT
|
21
|
-
This file includes the useful text.
|
22
|
-
|
23
|
-
@[:verbatim](#{reusable_text_file_name})
|
24
|
-
EOT
|
25
|
-
)
|
26
|
-
|
27
|
-
# Example inclusion.
|
28
|
-
system(include_command)
|
29
|
-
|
30
|
-
File.write(
|
31
|
-
template_file_name,
|
32
|
-
<<EOT
|
33
|
-
### Use Case: Reuse Text
|
34
|
-
|
35
|
-
Use file inclusion to stay DRY (Don't Repeat Yourself).
|
36
|
-
|
37
|
-
Maintain reusable text in a separate file, then include it wherever it's needed.
|
38
|
-
|
39
|
-
#### File to Be Included
|
40
|
-
|
41
|
-
Here's a file containing some text that can be included:
|
42
|
-
|
43
|
-
@[:code_block](#{reusable_text_file_name})
|
44
|
-
|
45
|
-
#### Includer File
|
46
|
-
|
47
|
-
Here's a template file that includes it:
|
48
|
-
|
49
|
-
@[:code_block](#{includer_file_name})
|
50
|
-
|
51
|
-
#### Command
|
52
|
-
|
53
|
-
Here's the command to perform the inclusion (```--pristine``` suppresses inclusion comments):
|
54
|
-
|
55
|
-
```sh
|
56
|
-
#{include_command}
|
57
|
-
```
|
58
|
-
|
59
|
-
#### File with Inclusion
|
60
|
-
|
61
|
-
Here's the finished file with the inclusion:
|
62
|
-
|
63
|
-
@[:code_block](#{included_file_name})
|
64
|
-
EOT
|
65
|
-
)
|
66
|
-
|
67
|
-
# Build use case.
|
68
|
-
build_command = "markdown_helper include --pristine #{template_file_name} #{use_case_file_name}"
|
69
|
-
system(build_command)
|
@@ -1,14 +0,0 @@
|
|
1
|
-
### Evergreen Examples
|
2
|
-
|
3
|
-
Example code and output that's embedded in a markdown file is dead text that may no longer be correct.
|
4
|
-
|
5
|
-
Use the markdown helper to include example code and output -- but only after the project "build" has re-run the code and refreshed the output!
|
6
|
-
|
7
|
-
Here's how:
|
8
|
-
|
9
|
-
1. Maintain each code example in a separate executable file.
|
10
|
-
1. Maintain markdown files that have include descriptions, rather than embedded code and output.
|
11
|
-
1. At project "build time" (controlled by a suitable build tool):
|
12
|
-
1. Execute each code example, capturing its output to one or more files.
|
13
|
-
1. Check output for errors and validity.
|
14
|
-
1. Run the markdown helper to re-assemble the markdown files.
|