Glyph was designed and developed by Fabio Cevasco (h3rald).
2 |Special thanks to the following individuals who contributed to Glyph by reporting and fixing issues, proposing and implementing new features or provided Glyph-related resources and plugins:
3 |Copyright © 2010-2012 Fabio Cevasco, http://www.h3rald.com
2 |Permission is hereby granted, free of charge, to any person obtaining a copy 3 | of this software and associated documentation files (the "Software"), to deal 4 | in the Software without restriction, including without limitation the rights 5 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 6 | copies of the Software, and to permit persons to whom the Software is 7 | furnished to do so, subject to the following conditions:
8 |The above copyright notice and this permission notice shall be included in 9 | all copies or substantial portions of the Software.
10 |THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 11 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 12 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 13 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 14 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 15 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 16 | THE SOFTWARE. 17 |
-------------------------------------------------------------------------------- /Rakefile: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env ruby 2 | # encoding: utf-8 3 | 4 | lib = File.expand_path(File.dirname(__FILE__) + '/lib') 5 | $: << lib 6 | require 'rubygems' 7 | require 'rake/clean' 8 | require "#{lib}/glyph.rb" 9 | 10 | task :default => :spec 11 | 12 | # RSpec 13 | begin 14 | require "rspec/core/rake_task" 15 | RSpec::Core::RakeTask.new(:spec) do |t| 16 | t.pattern = 'spec/**/*_spec.rb' 17 | t.rspec_opts = ["-c", "-f progress", "-r ./spec/spec_helper.rb"] 18 | end 19 | RSpec::Core::RakeTask.new(:test) do |t| 20 | args = ARGV.reverse 21 | args.pop 22 | t.pattern = args.join " " 23 | t.rspec_opts = ["-c", "-f progress", "-r ./spec/spec_helper.rb"] 24 | end 25 | rescue LoadError 26 | puts "RSpec is not available. Install it with: gem install rspec" 27 | end 28 | 29 | # Yard 30 | begin 31 | require 'yard' 32 | YARD::Rake::YardocTask.new(:yardoc) do |t| 33 | t.files = ['lib/**/*.rb', './README.textile', 'lib/*.rb'] 34 | t.options = ['--no-private'] 35 | end 36 | rescue LoadError 37 | puts "YARD is not available. Install it with: gem install yard" 38 | end 39 | 40 | FileList['tasks/**/*.rake'].each { |t| load t} 41 | -------------------------------------------------------------------------------- /benchmark.rb: -------------------------------------------------------------------------------- 1 | require 'rubygems' 2 | require 'pathname' 3 | require 'extlib' 4 | require 'bluecloth' 5 | require 'redcloth' 6 | require 'benchmark' 7 | require Pathname.new(__FILE__).parent/"lib/glyph.rb" 8 | 9 | 10 | 11 | def macro_exec(text) 12 | Glyph::Interpreter.new(text).document.output 13 | end 14 | 15 | def sep 16 | puts "="*100 17 | end 18 | 19 | N = 50 20 | 21 | def rep(x, title, &block) 22 | x.report(title.to_s) { N.times(&block) } 23 | end 24 | 25 | def reset_glyph 26 | Glyph.lite_mode = true 27 | Glyph['system.quiet'] = true 28 | end 29 | 30 | 31 | text = %{ 32 | Lorem ipsum dolor sit amet, consectetur _adipisicing elit_, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 33 | Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. 34 | * Duis aute irure dolor in *reprehenderit* in voluptate velit esse cillum dolore eu fugiat nulla pariatur. 35 | * Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. 36 | } 37 | html = %{ 38 | p[Lorem ipsum dolor sit amet, consectetur em[adipisicing elit], sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.] 39 | p[Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.] 40 | ul[ 41 | li[Duis aute irure dolor in strong[reprehenderit] in voluptate velit esse cillum dolore eu fugiat nulla pariatur.] 42 | li[Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.] 43 | ] 44 | } 45 | 46 | reset_glyph 47 | Glyph.run! 'load:all' 48 | Benchmark.bm(30) do |x| 49 | 50 | sep 51 | puts " => Core Classes" 52 | rep(x, "Glyph::Interpreter.new.parse") {Glyph::Interpreter.new(text).parse} 53 | rep(x, "Glyph::Parser.new(text).parse") {Glyph::Parser.new(text).parse} 54 | sep 55 | puts " => Macro Set: Glyph" 56 | sep 57 | rep(x, "section[...]") { macro_exec "section[#{text}]" } 58 | rep(x, "snippet[...]") { macro_exec "snippet:[test|#{text}]snippet[test]" } 59 | rep(x, "textile[...]") { macro_exec "textile[#{text}]" } 60 | rep(x, "markdown[...]") { macro_exec "markdown[#{text}]" } 61 | rep(x, "HTML text") { macro_exec html } 62 | sep 63 | rep(x, "Markdown (BlueCloth)") {BlueCloth.new(text).to_html } 64 | rep(x, "Textile (RedCloth)") {RedCloth.new(text).to_html } 65 | sep 66 | puts " => Macro Set: XML" 67 | reset_glyph 68 | Glyph['options.macro_set'] = 'xml' 69 | Glyph.run! 'load:all' 70 | rep(x, "HTML text") { macro_exec html } 71 | end 72 | -------------------------------------------------------------------------------- /bin/glyph: -------------------------------------------------------------------------------- 1 | #!/usr/bin/ruby 2 | $: << File.expand_path(File.dirname(__FILE__) + '/../lib') 3 | require 'glyph' 4 | require 'glyph/commands' 5 | 6 | 7 | run(ARGV) 8 | -------------------------------------------------------------------------------- /book/compile: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env ruby 2 | 3 | Dir.chdir '../styles' 4 | 5 | system 'sh "generate"' 6 | 7 | Dir.chdir '../book' 8 | 9 | require_relative '../lib/glyph.rb' 10 | require_relative '../lib/glyph/commands.rb' 11 | 12 | run ["compile", '-f', 'pdf'] 13 | -------------------------------------------------------------------------------- /book/compile_web: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env ruby 2 | 3 | Dir.chdir '../styles' 4 | 5 | system 'sh "generate"' 6 | 7 | Dir.chdir '../book' 8 | 9 | require_relative '../lib/glyph.rb' 10 | require_relative '../lib/glyph/commands.rb' 11 | 12 | run ["-d", "compile", '-f', 'h3rald'] 13 | -------------------------------------------------------------------------------- /book/config.yml: -------------------------------------------------------------------------------- 1 | --- 2 | :document: 3 | :output: html 4 | :subtitle: Rapid Document Authoring Framework 5 | :author: Fabio Cevasco 6 | :draft: true 7 | :revision: v0.5.2 8 | :filename: glyph 9 | :title: Glyph 10 | :styles: link 11 | :output: 12 | :h3rald: 13 | :multifile: true 14 | :extension: .html 15 | :filter_target: html 16 | :base: /glyph/book/ 17 | :macro_reps: html5 18 | :layout_dir: web5 19 | :layouts: 20 | :topic: bookpage 21 | :index: bookindex 22 | :pdf: 23 | :generator: prince 24 | -------------------------------------------------------------------------------- /book/images/glyph/commands_tasks.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/h3rald/glyph/2472b55a13bb530e98b5f1b171a7bbd6f6968b68/book/images/glyph/commands_tasks.png -------------------------------------------------------------------------------- /book/images/glyph/document_generation.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/h3rald/glyph/2472b55a13bb530e98b5f1b171a7bbd6f6968b68/book/images/glyph/document_generation.png -------------------------------------------------------------------------------- /book/images/glyph/glyph.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/h3rald/glyph/2472b55a13bb530e98b5f1b171a7bbd6f6968b68/book/images/glyph/glyph.png -------------------------------------------------------------------------------- /book/lib/commands/commands.rb: -------------------------------------------------------------------------------- 1 | GLI.desc 'Generates a specific file required for Glyph releases' 2 | arg_name "file_name" 3 | command :generate do |c| 4 | c.action do |global_options,options,args| 5 | if args.blank? then 6 | raise RuntimeError, "You must specify a file to generate" 7 | else 8 | Glyph.run 'custom:generate', args[0] 9 | end 10 | end 11 | end 12 | -------------------------------------------------------------------------------- /book/lib/layouts/bookindex.glyph: -------------------------------------------------------------------------------- 1 | ----- 2 | permalink: index 3 | title: Glyph Documentation 4 | type: page 5 | ----- 6 | toc[] 7 | -------------------------------------------------------------------------------- /book/lib/layouts/bookpage.glyph: -------------------------------------------------------------------------------- 1 | ----- 2 | permalink: {{id}} 3 | title: Glyph – {{title}} 4 | type: page 5 | ----- 6 | navigation[{{id}}] 7 | {{contents}} 8 | navigation[{{id}}] 9 | -------------------------------------------------------------------------------- /book/lib/layouts/project.glyph: -------------------------------------------------------------------------------- 1 | ----- 2 | permalink: glyph 3 | filters_pre: 4 | - erb 5 | title: "Glyph" 6 | subtitle: "A Rapid Document Authoring Framework" 7 | type: project 8 | github: glyph 9 | links: 10 | - "Repository": http://www.github.com/h3rald/glyph/ 11 | - "Download": http://www.rubygems.org/gems/glyph 12 | - "Documentation": /glyph/book/ 13 | - "User Group": http://groups.google.com/group/glyph-framework 14 | status: Active 15 | version: %[Glyph::VERSION] 16 | ----- 17 | 18 | <%= render 'project_data', :tag => 'glyph' %> 19 | 20 | {{contents}} 21 | 22 | <%= render 'project_updates', :tag => 'glyph' %> 23 | -------------------------------------------------------------------------------- /book/lib/tasks/tasks.rake: -------------------------------------------------------------------------------- 1 | namespace :custom do 2 | task :generate, [:file] do |t, args| 3 | generate = lambda do |source, destination| 4 | Glyph.info "Generating #{destination}..." 5 | Glyph.compile Glyph::PROJECT/"text/#{source}.glyph", "#{Glyph::PROJECT/"../#{destination}.textile"}" 6 | end 7 | files = { 8 | :AUTHORS => :acknowledgements, 9 | :CHANGELOG => :changelog, 10 | :LICENSE => :license, 11 | :README => :introduction 12 | } 13 | arg = args[:file].upcase.to_sym 14 | raise RuntimeError, "Unknown file '#{arg}.glyph'" unless files.keys.include? arg 15 | generate.call files[arg], arg 16 | Glyph.info "Done." 17 | end 18 | end 19 | 20 | namespace :generate do 21 | desc "Create output for h3rald.com integration" 22 | task :h3rald => [:web5] do 23 | dir = Glyph::PROJECT/'output/h3rald' 24 | (dir/"glyph/book").mkpath 25 | # Copy files in subdir 26 | (dir).find do |i| 27 | if i.file? then 28 | next if i.to_s.match(Regexp.escape(dir/'glyph')) 29 | dest = dir/"glyph/book/#{i.relative_path_from(Glyph::PROJECT/dir)}" 30 | src = i.to_s 31 | Pathname.new(dest).parent.mkpath 32 | file_copy src, dest 33 | end 34 | end 35 | # Remove files from output dir 36 | dir.children.each do |c| 37 | unless c == dir/'glyph' then 38 | c.directory? ? c.rmtree : c.unlink 39 | end 40 | end 41 | (dir/'glyph/book/images/glyph/glyph.eps').unlink 42 | (dir/'glyph/book/images/glyph/glyph.svg').unlink 43 | # Create project page 44 | project = Glyph.filter %{layout/project[ 45 | @contents[#{file_load(Glyph::PROJECT/'text/introduction.glyph')}] 46 | ]} 47 | file_write dir/"glyph.textile", project 48 | end 49 | end 50 | -------------------------------------------------------------------------------- /book/resources/document_generation.txt: -------------------------------------------------------------------------------- 1 | participant generate_document 2 | participant Interpreter 3 | participant Parser 4 | participant Document 5 | participant SyntaxNode 6 | participant Macro 7 | 8 | 9 | generate_document->Interpreter: new 10 | Interpreter->Parser: new 11 | generate_document->Interpreter: parse 12 | Interpreter->Parser: parse 13 | Parser-->Interpreter: tree (SyntaxNode) 14 | Interpreter->Document: new 15 | generate_document->Interpreter: process 16 | Interpreter->Document: analyze 17 | loop Processing 18 | Document->SyntaxNode: evaluate 19 | alt if macro node 20 | SyntaxNode->Macro: expand 21 | end 22 | end 23 | Document-->Interpreter: :analized 24 | generate_document->Interpreter: postprocess 25 | Interpreter->Document: finalize 26 | loop Post-processing 27 | note over Document 28 | Replace all escape sequences 29 | and placeholders in the 30 | final text output 31 | end note 32 | end 33 | Document-->Interpreter: :finalized 34 | Interpreter-->generate_document: document -------------------------------------------------------------------------------- /book/text/acknowledgements.glyph: -------------------------------------------------------------------------------- 1 | txt[ 2 | Glyph was designed and developed by =>[http://www.h3rald.com|Fabio Cevasco] (h3rald). 3 | 4 | Special thanks to the following individuals who contributed to Glyph by reporting and fixing issues, proposing and implementing new features or provided Glyph-related resources and plugins: 5 | * =>[http://www.jabbslad.com|Jamie Atkinson] (Jabbslad) 6 | * =>[http://koraktor.github.com|Sebastian Staudt] (koraktor) 7 | * =>[http://balcone.eveel.ru|Dmitry A. Ustalov] (eveel) 8 | * =>[http://www.stuartellis.eu|Stuart Ellis] (stuartellis) 9 | * Eric Givens (darthzippy) 10 | * =>[http://www.taylored-software.com/|Tammy Cravit] (tammycravit) 11 | * =>[https://github.com/grv87|Basil Peace] (grv87) 12 | ] 13 | 14 | -------------------------------------------------------------------------------- /book/text/compiling/lite_mode.glyph: -------------------------------------------------------------------------------- 1 | p[Glyph's primary goal is to author complex documents like books or manuals. In order to do so, a Glyph project is required to keep everything organized and automated via a set of predefined conventions, exactly like Ruby on Rails or other similar frameworks do.] 2 | p[If you want to write a one-page article or a short draft, however, creating and managing Glyph projects can be an unnecessary burden. Luckily, you don't have to: you can use Glyph to compile single files containing Glyph code, by adding one parameter (or two if you want to specify a custom destination file) to the #>[compile], like this:] 3 | p[code[glyph compile source.glyph destination.htm]] 4 | p[This command will process a file called code[source.glyph] and produce an HTML file called code[destination.htm].] 5 | section[ 6 | @title[Limitations] 7 | @id[lite_limitations] 8 | &:[only_defined_through|can only be defined inside the source file, using the] 9 | txt[ 10 | &:[referenced_with_path|must be referenced with their absolute path, or a path relative to the current directory] 11 | This sort of "lite" mode comes with a few minor limitations: 12 | * Snippets &[only_defined_through] %>[snippet:]. 13 | * Project configuration settings &[only_defined_through] %>[config:]. 14 | * Custom macros &[only_defined_through] %>[macro:]. 15 | * Images &[referenced_with_path], and will not be copied anywhere when the output file is generated. 16 | * Stylesheets &[referenced_with_path], or the name of an existing Glyph =>[#default_stylesheets|system stylesheet]. 17 | * The files included through the %>[include] &[referenced_with_path]. 18 | ] 19 | ] 20 | -------------------------------------------------------------------------------- /book/text/compiling/programmatic_usage.glyph: -------------------------------------------------------------------------------- 1 | txt[ 2 | Besides using Glyph from the command line, you can also use it straight from your code. Glyph's public =>[&[rubydoc]|API] is simple and can be used to: 3 | * Retrieve and update configuration settings (using @Glyph\[\]@ and @Glyph\[\]=@) 4 | * Filter text to HTML (using @Glyph#filter@) 5 | * Compile Glyph source files into HTML or PDF files (using @Glyph#compile@) 6 | 7 | That's pretty much it. Of course, both the @filter@ and @compile@ method cause Glyph to run in =>[#lite_mode|_lite_ mode], so the same =>[#lite_limitations|limitations] apply. 8 | ] 9 | tip[ 10 | txt[ 11 | For an example on how to use Glyph programmatically (specifically in conjunction with the =>[http://nanoc.stoneship.org/|nanoc] static site generator), see =>[http://github.com/h3rald/h3rald|h3rald.com source code], in particular: 12 | * =>[http://github.com/h3rald/h3rald/blob/master/lib/glyph_filter.rb|lib/glyph_filter.rb] -- using the @Glyph#filter@ method. 13 | * =>[http://github.com/h3rald/h3rald/blob/master/lib/glyph_context.rb|lib/glyph_context.rb] -- using the @Glyph#compile@ method to generate PDF files. 14 | ] 15 | ] 16 | section[ 17 | @title[Modes] 18 | @id[modes] 19 | p[It is possible to specify some flags (or "modes") to make Glyph behave slightly different than normal, as shown in the following table (by default, none of these is used).] 20 | table[ 21 | tr[ 22 | th[Name] 23 | th[Writer Method] 24 | th[Reader Method] 25 | th[Description] 26 | ] 27 | tr[ 28 | td[Test Mode] 29 | td[code[Glyph.test_mode=]] 30 | td[code[Glyph.test?]] 31 | td[Used internally by the code[rake spec] task to run Glyph's specs.] 32 | ] 33 | tr[ 34 | td[Library Mode] 35 | td[code[Glyph.library_mode=]] 36 | td[code[Glyph.library?]] 37 | td[If enabled, the #>[compile] command will raise exceptions instead of printing errors on the screen. Enabled by the code[Glyph.compile] command.] 38 | ] 39 | tr[ 40 | td[Debug Mode] 41 | td[code[Glyph.debug_mode=]] 42 | td[code[Glyph.debug?]] 43 | td[If enabled, additional diagnostic information (such as backtraces or macro values) will be displayed. Enabled by specifying the =>[#debug_switch|debug switch] when running a Glyph command.] 44 | ] 45 | tr[ 46 | td[Lite Mode] 47 | td[code[Glyph.lite_mode=]] 48 | td[code[Glyph.lite?]] 49 | td[ 50 | txt[ 51 | Used to compile =>[#lite_mode|single files]. Enabled by: 52 | * The @Glyph.compile@ and @Glyph.filter@ methods. 53 | * The #>[compile], if at least one parameter is supplied. 54 | ] 55 | ] 56 | ] 57 | tr[ 58 | td[Safe Mode] 59 | td[code[Glyph.safe_mode=]] 60 | td[code[Glyph.safe?]] 61 | td[ 62 | txt[ 63 | If enabled, the following macros cannot be used and will return an error: 64 | * %>[ruby] 65 | * %>[macro:] 66 | * %>[include] 67 | * %>[define:] 68 | * %>[config:] 69 | ] 70 | ] 71 | ] 72 | ] 73 | ] 74 | -------------------------------------------------------------------------------- /book/text/config/document.glyph: -------------------------------------------------------------------------------- 1 | The following configuration settings are related to the current Glyph document. Therefore, you should update them right after creating a project. 2 | 3 | config_table[ 4 | ref_config[document.author| 5 | The author of the document. 6 | ] 7 | ref_config[document.cover| 8 | The image used as the document cover (used only for e-book generation). 9 | ] 10 | ref_config[document.draft| 11 | If set to @true@, the document is considered a draft, so =>[#m_draftcomment|draft comments] and =>[#m_todo|todo items] will be displayed. 12 | ] 13 | ref_config[document.filename| 14 | The name of the output file. 15 | ] 16 | ref_config[document.output| 17 | The format of the output file. It can be set to: 18 | %[=Glyph['output'].keys.reject{\|v\| v == :h3rald }.map{\|v\| "* @#{v}@"}.sort.join("\n")=] 19 | ] 20 | ref_config[document.revision| 21 | The document's revision. 22 | ] 23 | ref_config[document.source| 24 | The main source file to compile. It can be also be overridden by calling the #>[compile] with the @-s@ option. 25 | ] 26 | ref_config[document.styles| 27 | How to process stylesheets. It can be set to one of the following values: 28 | * @embed@ -- Embed stylesheets within the document. 29 | * @link@ -- Link stylesheets. 30 | * @import@ -- Import stylesheets using the code[@import] CSS directive. 31 | ] 32 | ref_config[document.subtitle| 33 | The subtitle of the document, displayed using the %>[subtitle]. 34 | ] 35 | ref_config[document.title| 36 | The title of the document, displayed using the %>[title]. 37 | ] 38 | ref_config[document.isbn| 39 | The ISBN of the document, for e-book generation. 40 | ] 41 | ] 42 | -------------------------------------------------------------------------------- /book/text/config/filters.glyph: -------------------------------------------------------------------------------- 1 | These settings are used to configure some special options related to output filters and highlighters. 2 | 3 | config_table[ 4 | ref_config[filters.coderay.*| 5 | Some &[coderay]-specific =>[http://coderay.rubychan.de/doc/classes/CodeRay/Encoders/HTML.html|options]. 6 | ] 7 | ref_config[filters.highlighter| 8 | The current highlighter to use. It can be set to @coderay@ or @ultraviolet@ 9 | ] 10 | ref_config[filters.markdown.converter| 11 | The name of the markdown converter to use with the %>[markdown]. It can be set to one of the following values: 12 | * BlueCloth 13 | * RDiscount 14 | * Maruku 15 | * Kramdown 16 | 17 | If not set, Glyph tests for the presence of each gem in the same order, until one is found. 18 | ] 19 | ref_config[filters.redcloth.restrictions| 20 | An @Array@ containing restrictions applied to RedCloth, used by the %>[textile] (see =>[http://redcloth.rubyforge.org/classes/RedCloth/TextileDoc.html|RedCloth Documentation] for more information). 21 | ] 22 | ref_config[filters.ultraviolet.line_numbers| 23 | Whether the &[uv] highlighter should display line numbers or not. 24 | ] 25 | ref_config[filters.ultraviolet.theme| 26 | The theme used by the &[uv] highlighter. 27 | ] 28 | ] 29 | -------------------------------------------------------------------------------- /book/text/config/options.glyph: -------------------------------------------------------------------------------- 1 | The following configuration settings are used to enable or disable specific Glyph functionalities and behaviors. 2 | 3 | config_table[ 4 | ref_config[options.filters_by_file_extension| 5 | If set to @true@, a filter macro is applied to included files, based on their extensions (\/fmi[including files|#incl]). 6 | ] 7 | ref_config[options.macro_set| 8 | Determines which macro set will be loaded. It can be set to: 9 | * glyph -- Loads core, filter, xml macros plus all macros necessary for the $>[document.output]. 10 | * xml -- Loads core and xml macros. 11 | * core -- Loads core macros only. 12 | ] 13 | ref_config[options.safe_mode| 14 | Enables Safe Mode (\/fmi[Glyph modes|#modes]). 15 | ] 16 | ref_config[options.url_validation| 17 | If set to _true_, every external link will be validated (see =>[#links]). 18 | ] 19 | ref_config[options.xml_blacklist| 20 | The XML tags listed here cannot be generated using Glyph code. 21 | ] 22 | ref_config[options.xml_fallback| 23 | If set to true, any unknown macro name will considered an XML element (see =>[#other_elements]). 24 | ] 25 | ref_config[options.ebook.converter| 26 | The full path name of the ebook-convert command. Defaults to /usr/bin/ebook-convert.] 27 | ] 28 | -------------------------------------------------------------------------------- /book/text/config/output.glyph: -------------------------------------------------------------------------------- 1 | &:[o_multifile| 2 | If set to _true_, the document will be rendered in multiple files, according to the specified =>[#topics|topics]. 3 | ] 4 | &:[o_extension| 5 | The extension to use for the output file(s). 6 | ] 7 | &:[o_filter_target| 8 | The output target for filters. It can be set to @html@ (for RedCloth and MarkDown) or @latex@ (RedCloth-only). 9 | ] 10 | &:[o_through| 11 | The intermediate format from which a PDF file is generated. It can be set to @html@ or @html5@. 12 | ] 13 | &:[o_macro_reps| 14 | The name of the representation file from which macro representation will be loaded. 15 | ] 16 | &:[o_layout_dirs| 17 | The directories from which layout macros will be loaded (both in Glyph's home and the current project directory). 18 | ] 19 | &:[o_layouts.topic| 20 | The name of the layout to use to render topic files. 21 | ] 22 | &:[o_layouts.index| 23 | The name of the layout to use to render the document index file. 24 | ] 25 | &:[o_base| 26 | The directory to use as root for all link paths. 27 | ] 28 | &:[o_calibre| 29 | An array of options to configure Calibre. See the =>[http://calibre-ebook.com/user_manual/cli/ebook-convert-3.html|full list]. 30 | ] 31 | These settings are used to configure output-specific options. 32 | 33 | 34 | section[ 35 | @title[output.epub.*] 36 | config_table[ 37 | out_cfg[epub.extension] 38 | out_cfg[epub.filter_target] 39 | ref_config[output.epub.generator| 40 | The external program used to generate EPUB files. It must be set to @calibre@. 41 | ] 42 | out_cfg[epub.calibre] 43 | out_cfg[epub.macro_reps] 44 | out_cfg[epub.multifile] 45 | ] 46 | ] 47 | section[ 48 | @title[output.mobi.*] 49 | config_table[ 50 | out_cfg[mobi.extension] 51 | out_cfg[mobi.filter_target] 52 | ref_config[output.mobi.generator| 53 | The external program used to generate MOBI files. It must be set to @calibre@. 54 | ] 55 | out_cfg[mobi.calibre] 56 | out_cfg[mobi.macro_reps] 57 | out_cfg[mobi.multifile] 58 | ] 59 | ] 60 | section[ 61 | @title[output.pdf.*] 62 | config_table[ 63 | out_cfg[pdf.extension] 64 | out_cfg[pdf.filter_target] 65 | out_cfg[pdf.through] 66 | ref_config[output.pdf.generator| 67 | The external program used to generate PDF files. It can be set to @prince@ or @wkhtmltopdf@. 68 | ] 69 | out_cfg[pdf.macro_reps] 70 | out_cfg[pdf.multifile] 71 | ] 72 | ] 73 | section[ 74 | @title[output.html.*] 75 | config_table[ 76 | out_cfg[html.extension] 77 | out_cfg[html.filter_target] 78 | out_cfg[html.macro_reps] 79 | out_cfg[html.multifile] 80 | ] 81 | ] 82 | section[ 83 | @title[output.html5.*] 84 | config_table[ 85 | out_cfg[html5.extension] 86 | out_cfg[html5.filter_target] 87 | out_cfg[html5.macro_reps] 88 | out_cfg[html5.multifile] 89 | ] 90 | ] 91 | section[ 92 | @title[output.web.*] 93 | config_table[ 94 | out_cfg[web.base] 95 | out_cfg[web.extension] 96 | out_cfg[web.filter_target] 97 | out_cfg[web.layout_dirs] 98 | out_cfg[web.layouts.index] 99 | out_cfg[web.layouts.topic] 100 | out_cfg[web.macro_reps] 101 | out_cfg[web.multifile] 102 | ] 103 | ] 104 | section[ 105 | @title[output.web5.*] 106 | config_table[ 107 | out_cfg[web5.base] 108 | out_cfg[web5.extension] 109 | out_cfg[web5.filter_target] 110 | out_cfg[web5.layout_dirs] 111 | out_cfg[web5.layouts.index] 112 | out_cfg[web5.layouts.topic] 113 | out_cfg[web5.macro_reps] 114 | out_cfg[web5.multifile] 115 | ] 116 | ] 117 | -------------------------------------------------------------------------------- /book/text/extending/bookmarks_headers.glyph: -------------------------------------------------------------------------------- 1 | txt[ 2 | The =>[&[rubydoc]/Macro|@Glyph::Macro@] class also includes a few methods to check and store bookmarks and headers. Consider for example the following source code for the %>[anchor]: 3 | ] 4 | 5 | highlight[=ruby| 6 | macro :anchor do 7 | min_parameters 1 8 | max_parameters 2 9 | bookmark :id => param(0), :title => param(1), :file => @source_file 10 | @data[:id] = param 0 11 | @data[:title] = param 1 12 | render 13 | end 14 | =] 15 | 16 | txt[ 17 | The @bookmark?@ method can be used to check the existance of a particular ID within the whole document, while the @bookmark@ method is used to store bookmark IDs and titles. In a similar way, you can use @header?@ and @header@ methods to check the existance of headers within the documents or store new ones. 18 | ] 19 | -------------------------------------------------------------------------------- /book/text/extending/command.glyph: -------------------------------------------------------------------------------- 1 | txt[ 2 | Glyph relies on =>[http://davetron5000.github.com/gli/|GLI] for defining commands. This useful library provides a high-level framework for creating command-line interface similar to =>[http://git-scm.com/|Git], its DSL takes care of pretty much everything, from managing command line arguments and options to providing an interactive help system. 3 | ] 4 | section[ 5 | @title[Creating a 'glyph generate' command] 6 | txt[ 7 | Consider the custom task defined in =>[#custom_generate_task]. Creating a custom command to call it is fairly straightforward. 8 | 9 | First of all, create a @lib/commands@ folder in your project directory. Then, create a @.rb@ file within it, e.g. @commands.rake@. 10 | 11 | Finally, here's the source of the command: 12 | ] 13 | highlight[=ruby| 14 | GLI.desc 'Generates a specific file required for Glyph releases' 15 | arg_name "file_name" 16 | command :generate do \|c\| 17 | c.action do \|global_options,options,args\| 18 | if args.blank? then 19 | raise RuntimeError, "You must specify a file to generate" 20 | else 21 | Glyph.run 'custom:generate', args[0] 22 | end 23 | end 24 | end 25 | =] 26 | txt[ 27 | That's it. If you try to run @glyph help@ within your project directory, notice that there's a new entry for the generate command: 28 | ] 29 | highlight[html| 30 | $ glyph help 31 | ===================================== 32 | Glyph v\/%[Glyph::VERSION] 33 | ===================================== 34 | usage: glyph command \[options\] 35 | 36 | Options: 37 | -d, --debug - Enable debugging 38 | 39 | Commands: 40 | add - Add a new text file to the project 41 | compile - Compile the project 42 | config - Get/set configuration settings 43 | generate - Generates a specific file required for Glyph releases 44 | help - Shows list of commands or help for one command 45 | init - Create a new Glyph project 46 | outline - Display the document outline 47 | stats - Display statistics 48 | todo - Display all project TODO items 49 | ] 50 | p[You can now run the Glyph command as expected:] 51 | highlight[=html| 52 | $ glyph -d generate changelog 53 | -- Generating CHANGELOG... 54 | -- Done. 55 | =] 56 | ] 57 | -------------------------------------------------------------------------------- /book/text/extending/commands_tasks.glyph: -------------------------------------------------------------------------------- 1 | txt[ 2 | In most cases, you can extend Glyph just by creating your own =>[#macro_def|custom macros]. In some cases though, you may want to further customize Glyph to fit the needs of your project, in terms of creating =>[#custom_command|custom commands] and =>[#custom_task|custom tasks]. 3 | 4 | Glyph's modular architecture (and the Ruby language itself) lets you to add _arbitrary_ functionality to its core, simply by creating a few Ruby files and putting them in the right places. 5 | ] 6 | section[ 7 | @title[How Commands and Tasks work] 8 | @id[cmd_tasks_arch] 9 | txt[ 10 | Before creating custom Glyph commands and tasks, you should have a basic understanding on how they work, and which commands -- or better, which tasks -- are already available. 11 | 12 | The following diagram outlines the relationships between the default commands and some tasks: 13 | ] 14 | figure[glyph/commands_tasks.png|Some of Glyph default commands and tasks] 15 | txt[ 16 | As you can see: 17 | * All commands call at at least one task. 18 | * There are several task inter-dependencies spanning across three main Rake namespaces: 19 | ** @project:@ -- used for tasks affecting only the physical structure of the Glyph project. 20 | ** @load:@ -- used to load all kinds of files. 21 | ** @generate:@ -- used to generate files or copy files from source to output directories 22 | ] 23 | box[Example| 24 | txt[ 25 | Suppose you want to generate a PDF file by issuing the @glyph compile -f pdf@ command. Under the hood, Glyph calls the following tasks: 26 | # @load:config@ -- Load the configuration files 27 | # @load:tasks@ -- Load custom tasks (if any) 28 | # @load:commands@ -- Load custom commands (if any) 29 | # @load:snippets@ -- Load snippets from the @snippet.yml@ file 30 | # @load:macros@ -- Load macros 31 | # @load:all@ -- Dummy task used to call the previous ones 32 | # @generate:document@ -- Parse, analyze and finalize the Glyph document 33 | # @generate:images@ -- Copy images to the output directory (if any) 34 | # @generate:styles@ -- Copy stylesheets to the output directory (if necessary) 35 | # @generate:html@ -- Generate a standalone HTML file 36 | # @generate:pdf@ -- Generate a PDF file from a standalone HTML file 37 | ] 38 | ] 39 | ] 40 | -------------------------------------------------------------------------------- /book/text/extending/further_reading.glyph: -------------------------------------------------------------------------------- 1 | txt[ 2 | For more examples on how to create more complex macros, have a look at the =>[http://github.com/h3rald/glyph/tree/master/macros/|source code] of the existing ones. 3 | 4 | To gain a deeper understanding on how macros are executed, have a look at the following Glyph classes: 5 | * class[Glyph::Parser] 6 | * class[Glyph::SyntaxNode] 7 | * class[Glyph::Interpreter] 8 | * class[Glyph::Document] 9 | * class[Glyph::Macro] 10 | ] 11 | -------------------------------------------------------------------------------- /book/text/extending/layouts.glyph: -------------------------------------------------------------------------------- 1 | txt[ 2 | When generating =>[#topics|topic]-based outputs, Glyph uses _layouts_ to render topics as standalone documents. By default, the following two layout are used: 3 | * code[topic] -- used to render standard topics. 4 | * code[index] -- used to render the index page of your document. 5 | 6 | Layouts are nothing more than "fancy" Glyph macros defined using the Glyph language (i.e. by using =>[#rewriting|macro rewriting]) within a single code[.glyph] file. 7 | ] 8 | section[ 9 | @title[Topic Layout] 10 | p[The default layout used to render all web topics (the layout used for web5 topics is very similar) is defined as follows:] 11 | highlight[=html| 12 | document[ 13 | head[ 14 | style[default.css] 15 | ] 16 | body[ 17 | @class[topic] 18 | section[ 19 | @title[{{title}}] 20 | @id[{{id}}] 21 | navigation[{{id}}] 22 | {{contents}} 23 | navigation[{{id}}] 24 | ] 25 | ] 26 | ] 27 | =] 28 | txt[Note that it takes the following attributes, passed automatically by Glyph when processing each topic: 29 | * code[title] -- the title of the topic. 30 | * code[id] -- the ID of the topic. 31 | * code[contents] -- the body of the topic. 32 | ] 33 | ] 34 | section[ 35 | @title[Index Layout] 36 | @id[index_layout] 37 | p[The default layout used to render the web index page (the layout used for the web5 index is very similar) is defined as follows:] 38 | highlight[=html| 39 | document[ 40 | head[ 41 | style[default.css] 42 | ] 43 | body[ 44 | @class[topic] 45 | halftitlepage[ 46 | title[] 47 | subtitle[] 48 | author[] 49 | ] 50 | frontmatter[ 51 | toc[] 52 | ] 53 | ] 54 | ] 55 | =] 56 | p[Index layouts do not take any attribute or parameter (basically because they are used to produce only one page).] 57 | ] 58 | section[ 59 | @title[Creating a Custom Layout] 60 | txt[ 61 | To create a custom layout, proceed as follows: 62 | * Create a @.glyph@ file in the @lib/layouts@ directory, within your project, e.g. @mytopic.glyph@ 63 | * Add the layout code, making sure (for topic layouts) that all the attributes (@title@, @id@, @contents@) are specified correctly. 64 | * Set the @output.*.layouts.topic@ setting to the name of the new layout (@mytopic@). 65 | ] 66 | tip[You can override which layout to use on a specific topic by specifying it in a code[@layout] attribute.] 67 | ] 68 | 69 | -------------------------------------------------------------------------------- /book/text/extending/output_format.glyph: -------------------------------------------------------------------------------- 1 | txt[ 2 | As shown in =>[#cmd_tasks_arch], the #>[compile] command calls specific tasks defined in the @generate:@ Rake namespace to generate output files in a particular format. 3 | 4 | More specifically, when a @--format@ option is specified, the command looks for a task with the same name within the @generate:@ namespace. This makes adding new output formats to Glyph a fairly easy task, without the need to specify custom commands or similar. 5 | 6 | The following sections explain how the @h3rald@ output format was created to integrate this book into the =>[http://www.h3rald.com|H3RALD.com] website. 7 | ] 8 | section[ 9 | @title[Output Configuration] 10 | txt[ 11 | The first step required to add a new output format to Glyph is extending Glyph's configuration by adding the appropriate output hash, as follows: 12 | ] 13 | highlight[=yaml| 14 | :output: 15 | :h3rald: 16 | :multifile: true 17 | :extension: '.html' 18 | :filter_target: 'html' 19 | :base: '/glyph/book/' 20 | :macro_dirs: ['html', 'html5'] 21 | :layout_dirs: ['web5'] 22 | :layouts: 23 | :topic: bookpage 24 | :index: bookindex 25 | =] 26 | txt[ 27 | In particular, the following keys are mandatory: 28 | * multifile 29 | * extension 30 | * filter_target 31 | * base 32 | * macro_dirs 33 | * layout_dirs 34 | ] 35 | ] 36 | section[ 37 | @title[Creating a 'generate:h3rald' task] 38 | txt[ 39 | The next (and final) step involves creating a custom @h3rald@ task within the @generate:@ namespace. This task can be placed in any @.rake@ file within the @lib/tasks@ directory: 40 | ] 41 | highlight[=ruby| 42 | namespace :generate do 43 | desc "Create output for h3rald.com integration" 44 | task :h3rald => [:web5] do 45 | dir = Glyph::PROJECT/'output/h3rald' 46 | (dir/"glyph/book").mkpath 47 | # Copy files in subdir 48 | (dir).find do \|i\| 49 | if i.file? then 50 | next if i.to_s.match(Regexp.escape(dir/'glyph')) 51 | dest = dir/"glyph/book/#{i.relative_path_from(Glyph::PROJECT/dir)}" 52 | src = i.to_s 53 | Pathname.new(dest).parent.mkpath 54 | file_copy src, dest 55 | end 56 | end 57 | # Remove files from output dir 58 | dir.children.each do \|c\| 59 | unless c == dir/'glyph' then 60 | c.directory? ? c.rmtree : c.unlink 61 | end 62 | end 63 | (dir/'glyph/book/images/glyph/glyph.eps').unlink 64 | (dir/'glyph/book/images/glyph/glyph.svg').unlink 65 | # Create project page 66 | project = Glyph.filter %{layout:project[ 67 | @contents[#{file_load(Glyph::PROJECT/'text/introduction.glyph')}] 68 | ]} 69 | file_write dir/"glyph.textile", project 70 | end 71 | end 72 | =] 73 | p[In this case, this task does not actually renders files in a different format, it just moves the files generated by the @generate:web5@ task in different subdirectories.] 74 | p[Additionally, it also generates the =>[http://www.h3rald.com/glyph/|Glyph project page] from the book's introduction (note the usage of a raw custom layout macro).] 75 | ] 76 | -------------------------------------------------------------------------------- /book/text/extending/params_attrs.glyph: -------------------------------------------------------------------------------- 1 | txt[ 2 | Perhaps the most common things to do in a macro definition is accessing parameters and attributes. When doing so, it is important to consider whether we want to retrieve the _raw value_ of and attribute or parameter or its _expanded value_. The difference between the two will become clearer in the following sections and also in the =>[#interpreting] section. 3 | ] 4 | section[ 5 | @title[Accessing Expanded Values] 6 | @id[expanded_values] 7 | txt[ 8 | Normally, you just want to get the value of an attribute or parameter and use it in the macro. This means, in other words, its _expanded_ value, i.e. the value resulting from the expansion of the macros (if any) within the attribute or parameter. 9 | ] 10 | txt[ 11 | To access expanded values, use the following methods: 12 | * @parameter@ (or @param@): Returns the expanded value of the parameter specified by number. Other parameters are not expanded. 13 | * @value@: Returns the expanded value of the first parameter (i.e. like @parameter(0)@). 14 | * @attribute@ (or @attr@): Returns the expanded value of the attribute specified by name. Other attributes are not expanded. 15 | * @parameters@ (or @params@): Returns an array of expanded parameters. 16 | * @attributes@ (or @attrs@): Returns a hash of expanded attributes. 17 | 18 | ] 19 | 20 | ] 21 | section[ 22 | @title[Accessing Raw Values] 23 | p[While accessing expanded values is simple and immediate, in some cases it may not produce the desired results. Consider the following macro definition:] 24 | highlight[=ruby| 25 | macro :nest_section do 26 | interpret %{section[ 27 | @title[A] 28 | section[ 29 | @title[B] 30 | #{value} 31 | ] 32 | ]} 33 | end 34 | =] 35 | p[And suppose to use it as follows:] 36 | highlight[=ruby| 37 | nest_section[ 38 | section[ 39 | @title[Inner Section] 40 | ... 41 | ] 42 | ] 43 | =] 44 | p[It produces the following HTML code:] 45 | highlight[=html| 46 |@ and @@ tags.]
18 | @block_example[=
19 | code[
20 | def hello
21 | puts "Hello World"
22 | end
23 | ]
24 | =]
25 | @remarks[For code highlighting, see the %>[highlight].]
26 | @params[-p[0|The code to be formatted.]]
27 | ]
28 |
29 | ref_macro[
30 | @n[figure]
31 | @desc[Includes an image in the document, with an optional caption (see =>[#img_fig]).]
32 | @block_example[=
33 | figure[
34 | graph.png\|Monthly Pageviews
35 | @width[90%]
36 | ]
37 | =]
38 | @params[
39 | -p[0|&[img_file]]
40 | -p[1|The image caption &[opt].]
41 | ]
42 | @attrs[
43 | -a[*|&[img_attrs]]
44 | ]
45 | ]
46 |
47 | ref_macro[
48 | @n[image]
49 | @desc[Includes an image in the document]
50 | @block_example[=
51 | img[
52 | holidays/landscape.jpg
53 | @class[photo]
54 | @style[border: 1px solid black;]
55 | ]
56 | =]
57 | @params[
58 | -p[0|&[img_file]]
59 | ]
60 | @attrs[
61 | -a[*|&[img_attrs]]
62 | ]
63 | ]
64 |
65 | ref_macro[
66 | @n[navigation]
67 | @desc[Displays links to the document's TOC and the previous/next topic (used only in =>[#layouts|layouts]). ]
68 | @params[
69 | -p[0|The ID of the current topic.]
70 | ]
71 | ]
72 |
73 | ref_macro[
74 | @n[note]
75 | @desc[Creates a note @div@ containing the value.]
76 | @aliases[important, caution, tip]
77 | @example[=note[This is a note.]=]
78 | @params[-p[0|The text of the note.]]
79 | ]
80 |
81 | ref_macro[
82 | @n[pubdate]
83 | @desc[Evaluates to a date string (in the format: em[current_month] em[current_year]; i.e. _%B_ _%Y_), within a @@ tag. If a parameter is supplied, its value is used instead of the current date.]
84 | @example[=pubdate[]=]
85 | @params[-p[0|An alternative content for the _pubdate_ @div@.]]
86 | ]
87 |
88 | ref_macro[
89 | @n[revision]
90 | @desc[Renders the revision of the document (based on the $>[document.revision]) within a @@ tag.]
91 | @example[=revision[]=]
92 | ]
93 |
94 | ref_macro[
95 | @n[subtitle]
96 | @desc[Renders the subtitle of the document (based on the $>[document.subtitle]) within a @@ tag.]
97 | @example[=subtitle[]=]
98 | ]
99 |
100 | ref_macro[
101 | @n[title]
102 | @desc[Renders the title of the document (based on the $>[document.title]) within a @@ tag.]
103 | @example[=title[]=]
104 | ]
105 |
--------------------------------------------------------------------------------
/book/text/macros/macros_filters.glyph:
--------------------------------------------------------------------------------
1 | def:[filtered_section|
2 | ref_macro[
3 | @n[{{markup}}_section]
4 | @desc[Creates a section (see %>[section]) whose content can be formatted with {{markup}} markup.]
5 | @aliases[{{aliases}}]
6 | @block_example[=
7 | {{markup}}_section[
8 | @title[Test Section]
9 | @id[test]
10 | Some *{{markup}}* text.
11 | ]
12 | =]
13 | @params[-p[0|The text of the section]]
14 | @attrs[
15 | -a[title|The title of the section &[opt]]
16 | -a[id|The ID of the section &[opt]]
17 | -a[notoc|If not blank, the header will not appear in the Table of Contents. &[opt]]
18 | ]
19 | ]
20 | ]
21 | ref_macro[
22 | @n[markdown]
23 | @desc[
24 | Uses a Markdown converter (BlueCloth, RDiscount, Maruku or Kramdown) to transform the value into HTML if the =>[#cfg_output|code[output.*.filter_target]] setting is set to @html@.
25 |
26 | &[called_on_files] with a @.markdown@ or a @.md@ extension.
27 | ]
28 | @aliases[md]
29 | @example[=markdown[This is *emphasized* text.]=]
30 | @params[-p[0|The Markdown text to filter.]]
31 | ]
32 |
33 | filtered_section[
34 | @markup[markdown]
35 | @aliases[§md, md_section]
36 | ]
37 |
38 | ref_macro[
39 | @n[textile]
40 | @desc[
41 | Uses the RedCloth gem to transform the value into HTML or LaTeX, depending on the value of the =>[#cfg_output|code[output.*.filter_target]].
42 |
43 | &[called_on_files] with a @.textile@ or a @.txt@ extension.
44 | ]
45 | @aliases[txt]
46 | @example[=textile[This is a *strong emphasis*.]=]
47 | @params[-p[0|The Textile text to filter.]]
48 | ]
49 |
50 | filtered_section[
51 | @markup[textile]
52 | @aliases[§txt, txt_section]
53 | ]
54 |
55 | ref_macro[
56 | @n[highlight]
57 | @desc[Highlights a piece of source code according to the specified language. fmi[code highligting|#source_code].]
58 | @block_example[=
59 | highlight[ruby\|
60 | def hello
61 | puts "Hello World"
62 | end
63 | ]
64 | =]
65 | @params[
66 | -p[0|A programming language supported by the underlying highlighter.]
67 | -p[1|The code to highlight.]
68 | ]
69 | ]
70 |
--------------------------------------------------------------------------------
/book/text/macros/macros_inline.glyph:
--------------------------------------------------------------------------------
1 | ref_macro[
2 | @n[anchor]
3 | @desc[Creates a named anchor (or bookmark).]
4 | @aliases[bookmark, #]
5 | @example[=#[test\|Test Bookmark]=]
6 | @params[
7 | -p[0|The identifier of the bookmark]
8 | -p[1|The contents of the bookmark &[opt]]
9 | ]
10 | ]
11 |
12 | ref_macro[
13 | @n[draftcomment]
14 | @desc[If the $>[document.draft] is set to @true@, displays a draft comment within the document.]
15 | @aliases[dc]
16 | @example[=dc[This is printed only in draft documents.]=]
17 | @params[-p[0|The text of the comment.]]
18 | ]
19 |
20 | ref_macro[
21 | @n[fmi]
22 | @desc[Creates a _For More Information_ link (for an example usage, see the %>[link]).]
23 | @example[=fmi[creating links\|#links]=]
24 | @params[
25 | -p[0|The object that needs additional explanation.]
26 | -p[1|A valid bookmark within the document.]
27 | ]
28 | ]
29 |
30 | ref_macro[
31 | @n[link]
32 | @desc[Creates an hyperlink (\/fmi[creating links|#links]).]
33 | @aliases[\/=>]
34 | @example[=\/=>[http://www.h3rald.com\|H3RALD.com]=]
35 | @params[
36 | -p[0|A valid bookmark within the document or an URL.]
37 | -p[1|The text of the link &[opt].]
38 | ]
39 | ]
40 |
41 | ref_macro[
42 | @n[todo]
43 | @aliases[!]
44 | @desc[Saves the value as a TODO item, which can be printed using the #>[todo] and included in the document if the $>[document.draft] is set to @true@.]
45 | @example[=todo[Remember to do this.]=]
46 | ]
47 |
--------------------------------------------------------------------------------
/book/text/macros/macros_structure.glyph:
--------------------------------------------------------------------------------
1 | ref_macro[
2 | @n[article]
3 | @desc[
4 | Used to create a simple article. By default, it includes the following macros:
5 | * @document@
6 | ** @head@
7 | *** @style\[default.css\]@
8 | ** @body@
9 | *** @halftitlepage@
10 | **** @title@
11 | **** @pubdate@
12 | **** @subtitle@
13 | **** @author@
14 | ]
15 | @params[-p[0|The article contents.]]
16 | @attrs[
17 | -a[pre-title|Contents to include before the %>[title].]
18 | -a[post-title|Contents to include after the %>[title].]
19 | -a[head|Contents to include instead of the default code[head] macro.]
20 | -a[pubdate|Contents to include instead of the default code[pubdate] macro.]
21 | -a[halftitlepage|Contents to include instead of the default code[halftitlepage] macro.]
22 | ]
23 | ]
24 |
25 | ref_macro[
26 | @n[book]
27 | @desc[
28 | Used to create a book. By default, it includes the following macros:
29 | * @document@
30 | ** @head@
31 | *** @style\[default.css\]@
32 | ** @body@
33 | *** @titlepage@
34 | **** @title@
35 | **** @pubdate@
36 | **** @subtitle@
37 | **** @revision@
38 | **** @author@
39 | ]
40 | @params[-p[0|The article contents.]]
41 | @attrs[
42 | -a[pre-title|Contents to include before the %>[title].]
43 | -a[post-title|Contents to include after the %>[title].]
44 | -a[head|Contents to include instead of the default code[head] macro.]
45 | -a[pubdate|Contents to include instead of the default code[pubdate] macro.]
46 | -a[titlepage|Contents to include instead of the default code[titlepage] macro.]
47 | -a[frontmatter|Contents to include within a code[frontmatter] macro.]
48 | -a[bodymatter|Contents to include within a code[bodymatter] macro.]
49 | -a[backmatter|Contents to include within a code[backmatter] macro.]
50 | ]
51 | ]
52 |
53 | ref_macro[
54 | @n[document]
55 | @desc[Creates an @@ tag and a DOCTYPE declaration. Called internally by the %>[book] and the %>[article].]
56 | @params[-p[0|The document contents.]]
57 | ]
58 |
59 | ref_macro[
60 | @n[head]
61 | @desc[Creates a @@ tag, pre-populated with @title@ and author/copyright @@ tags.]
62 | @params[-p[0|The head contents.]]
63 | ]
64 |
65 | ref_macro[
66 | @n[section]
67 | @desc[Creates a section (@@ or @@ tag).]
68 | @aliases[%[=Glyph['system.structure'].values.flatten.uniq.map{\|a\| a.to_s }.push("section").sort.join(', ')=]]
69 | @block_example[=
70 | section[
71 | @title[Test Section]
72 | @id[test]
73 | ...
74 | ]
75 | =]
76 | @params[-p[0|The text of the section]]
77 | @attrs[
78 | -a[title|The title of the section &[opt]]
79 | -a[id|The ID of the section &[opt]]
80 | -a[notoc|If not blank, the header will not appear in the Table of Contents. &[opt]]
81 | ]
82 | ]
83 |
84 | ref_macro[
85 | @n[style]
86 | @desc[Embeds the content of a CSS or Sass file within a @