acdc_core/
lib.rs

1use clap::ValueEnum;
2
3/// Document type to use when converting document.
4#[derive(Debug, Clone, ValueEnum, Default)]
5pub enum Doctype {
6    /// The default doctype. In `DocBook`, this includes the appendix, abstract,
7    /// bibliography, glossary, and index sections. Unless you are making a book or a man
8    /// page, you don’t need to worry about the doctype. The default will suffice.
9    #[default]
10    Article,
11
12    /// Builds on the article doctype with the additional ability to use a top-level title
13    /// as part titles, includes the appendix, dedication, preface, bibliography,
14    /// glossary, index, and colophon. There’s also the concept of a multi-part book, but
15    /// the distinction from a regular book is determined by the content. A book only has
16    /// chapters and special sections, whereas a multi-part book is divided by parts that
17    /// each contain one or more chapters or special sections.
18    Book,
19
20    /// Used for producing a groff manpage for Unix and Unix-like operating systems. This
21    /// doctype instructs the parser to recognize a special document header and section
22    /// naming conventions for organizing the `AsciiDoc` content as a man page. See
23    /// Generate Manual Pages from `AsciiDoc` for details on how structure a man page
24    /// using `AsciiDoc` and generate it using Asciidoctor.
25    Manpage,
26
27    /// There may be cases when you only want to apply inline `AsciiDoc` formatting to input
28    /// text without wrapping it in a block element. For example, in the Asciidoclet
29    /// project (`AsciiDoc` in Javadoc), only the inline formatting is needed for the text
30    /// in Javadoc tags.
31    Inline,
32}
33
34impl std::fmt::Display for Doctype {
35    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
36        match self {
37            Doctype::Article => write!(f, "article"),
38            Doctype::Book => write!(f, "book"),
39            Doctype::Manpage => write!(f, "manpage"),
40            Doctype::Inline => write!(f, "inline"),
41        }
42    }
43}
44
45/// Safe mode to use when processing the document. This follows from what is described in
46/// <https://docs.asciidoctor.org/asciidoctor/latest/safe-modes/> and is intended to
47/// provide similar functionality as Asciidoctor.
48#[derive(Debug, Clone, ValueEnum, Default, PartialOrd, PartialEq)]
49pub enum SafeMode {
50    /// The `UNSAFE` safe mode level disables all security measures.
51    #[default]
52    Unsafe = 0,
53
54    /// The `SAFE` safe mode level prevents access to files which reside outside of the
55    /// parent directory of the source file. Include directives (`include::[]`) are
56    /// enabled, but paths to include files must be within the parent directory. This mode
57    /// allows assets (such as the stylesheet) to be embedded in the document.
58    Safe,
59
60    /// The `SERVER` safe mode level disallows the document from setting attributes that
61    /// would affect conversion of the document. This level trims docfile to its relative
62    /// path and prevents the document from:
63    ///
64    /// - setting source-highlighter, doctype, docinfo and backend
65    /// - seeing docdir (as it can reveal information about the host filesystem)
66    ///
67    /// It allows icons and linkcss. No includes from a url are allowed unless the
68    /// `allow-uri-read` attribute is set.
69    Server,
70
71    /// The `SECURE` safe mode level disallows the document from attempting to read files
72    /// from the file system and including their contents into the document. Additionally,
73    /// it:
74    ///
75    /// - disables icons
76    /// - disables include directives (`include::[]`)
77    /// - data can not be retrieved from URIs
78    /// - prevents access to stylesheets and JavaScript files
79    /// - sets the backend to html5
80    /// - disables docinfo files
81    /// - disables data-uri
82    /// - disables interactive (opts=interactive) and inline (opts=inline) modes for SVGs
83    /// - disables docdir and docfile (as these can reveal information about the host
84    ///   filesystem)
85    /// - disables source highlighting
86    ///
87    /// Note: `GitHub` processes `AsciiDoc` files using the `SECURE` mode.
88    Secure,
89}
acdc_core/lib.rs

acdc_core/
lib.rs
