cargo 0.38.0

Cargo, a package manager for Rust.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109

require 'asciidoctor/extensions' unless RUBY_ENGINE == 'opal'

include Asciidoctor

# An inline macro that generates links to related man pages.
#
# Usage
#
#   man:gittutorial[7]
#
class ManInlineMacro < Extensions::InlineMacroProcessor
  use_dsl

  named :man
  name_positional_attributes 'volnum'

  def process parent, target, attrs
    manname = target
    suffix = if (volnum = attrs['volnum'])
      "(#{volnum})"
    else
      nil
    end
    text = %(#{manname}#{suffix})
    if parent.document.basebackend? 'html'
      parent.document.register :links, target
      if manname == 'rustc'
        html_target = 'https://doc.rust-lang.org/rustc/index.html'
      elsif manname == 'rustdoc'
        html_target = 'https://doc.rust-lang.org/rustdoc/index.html'
      elsif manname == 'cargo'
        html_target = 'commands/index.html'
      else
        html_target = %(commands/#{manname}.html)
      end
      %(#{(create_anchor parent, text, type: :link, target: html_target).render})
    elsif parent.document.backend == 'manpage'
      %(\x1b\\fB#{manname}\x1b\\fP#{suffix})
    else
      text
    end
  end
end

# Creates a link to something in the cargo documentation.
#
# For HTML this creates a relative link (using mdbook's 0.1's base-style
# links). For the man page it gives a direct link to doc.rust-lang.org.
#
# Usage
#
#   linkcargo:reference/manifest.html[the manifest]
#
class LinkCargoInlineMacro < Extensions::InlineMacroProcessor
  use_dsl

  named :linkcargo
  name_positional_attributes 'text'

  def process parent, target, attrs
    text = attrs['text']
    if parent.document.basebackend? 'html'
      parent.document.register :links, target
      %(#{(create_anchor parent, text, type: :link, target: target).render})
    elsif parent.document.backend == 'manpage'
      target = %(https://doc.rust-lang.org/cargo/#{target})
      %(#{(create_anchor parent, text, type: :link, target: target).render})
    else
      %(#{text} <#{target}>)
    end
  end
end

# Backticks in the manpage renderer use the CR font (courier), but in most
# cases in a terminal this doesn't look any different. Instead, use bold which
# should follow man page conventions better.
class MonoPostprocessor < Extensions::Postprocessor
  def process document, output
    if document.basebackend? 'manpage'
      output = output.gsub(/\\f\(CR/, '\\fB')
    end
    output
  end
end

# General utility for converting text. Example:
#
#   convert:lowercase[{somevar}]
class ConvertInlineMacro < Extensions::InlineMacroProcessor
  use_dsl

  named :convert
  name_positional_attributes 'text'

  def process parent, target, attrs
    text = attrs['text']
    case target
    when 'lowercase'
      text.downcase
    end
  end
end

Extensions.register :uri_schemes do
  inline_macro ManInlineMacro
  inline_macro LinkCargoInlineMacro
  inline_macro ConvertInlineMacro
  postprocessor MonoPostprocessor
end