doc.dh

<> Dash Language Documentation
<> Document Advanced Syntax Hypertextual

@(adress)

< Note >
    That documentation was generated from a [document]> write in Dash by a convertion tool named [Dast]>.

>: https://github.com/ReMinoer/Dash/blob/master/doc.dh
>: https://github.com/ReMinoer/Dast


<-> Identity

    This language is called Dash. It's a markup language to write structured documents with a good plain-text feel.

    His name come from the multiples definition of the word :

    - Dash as the name for the *[character] {-}, used a lot in the language.
    - Dash as a *[fast movement], corresponding to a quick-note language.
    - Dash as a small amount of something, giving the idea of *[subtility] and *[optimization].
    - Dash as the action of *[destroy], with one target : the /[Markdown] language.

    Used file extensions are:

    - .dh : two character extension
    - .dash : name extension

    Majuscule extensions are also tolerated.


<-> Paragraphs

    << .dash-+ >>

        You can write paragraphs directly.

        Jump two lines to write another paragraphs.
        You can also back to the line in the same paragraph.

    <...>

    < Design note >
        Come back to the line in the same paragraph is handled in the language because it's a common plain text formatting.


<-> Lists

    You can list items by using {-} at the beginning of lines.

    << .dash-+ >>

        -Item A
        -Item B
        -Item C

    <...>

    You can describe trees by breaking the alignement with tabulations or spaces.

    << .dash-+ >>

        - Item A
            - Sub-item A1
                - Sub-sub-item A1a
            - Sub-item A2
                - Sub-sub-item A2a
                - Sub-sub-item A2b
        - Item B
            - Sub-item B1
                - Sub-sub-item B1a
                - Sub-sub-item B1b

    <...>

    < Design note >
        In Dash, a tabulation is equal to 4 spaces.

    You can also create numbered lists with {1- 2- 3-}.

    << .dash-+ >>

        1- Item 1
        2- Item 2
        3- Item 3

    <...>

    < Design note >
        Numbers used will be ignored by the parser. It will use items order to number them.
    
    If you don't want to use numbers and leave the order to the parser, we encourage you to use {$-}.

    << .dash-+ >>

        $- Item 1
        $- Item 2
        $- Item 3

    <...>

    < Design note >
        In Dash, {$} replace numbers when it's possible.

    Lastly, you can also add list headers and keypoints to list. For that, use {->}.

    << .dash-+ >>

        1-> Header
            - Item A
            - Item B
                -> Keypoint
                -> Keypoint
            - Item C
                -> Keypoint
        2-> Other header
            - Item
            -> Keypoint

    <...>

    You can combine all these types of lists on different levels if you want.

    << .dash-+ >>

        1-> First list
            1- Point A
            2- Point B
                -> Important stuff
            3- Point C
                -> Also very important stuff
        2-> Second list
            - Point D
                0- First item
                0- Second item
                0- Third item
            - Point E
            -> Conclusion

    <...>


<-> Titles

    To add a title, use {<->} at the beginning of the line.
    You can define subtitles by adding more {-} inside brackets.

    << .dash-+ >>

        <-> Title 1
        Paragraph of Title 1

        <--> Title 2
        Paragraph of Title 2

        <---> Title 3
        Paragraph of Title 3

    <...>


<-> Blocks

    You can also define structural blocks for highlight some paragraphs. For that, you must add a header before the paragraph, like so: {< Type >}

    << .dash-+ >>

        < Message > Here is a quote on one line.

    <...>

    << .dash-+ >>

        < Warning >
            Here is a warning on one line, declared on previous line.

    <...>

    You can also start a section with multiple block from the same type with {<< Type >>}. It will end at the next header. To come back to default paragraph blocks, use the empty header {<>}.

    << .dash-+ >>

        << Note >>
            Here is a note

            With multiple paragraphs.
        <...>

        Here is normal paragraph

    <...>

    < Design note >
        In fact, titles are blocks. Because there are very common, they have there own syntax, combining lists and blocks syntax.


<-> Emphasis

    The language handle the four most famous emphasis :

    - You can use *[bold] with {*[ ... ]}.
    - You can /[italic] some sentences or words with {/[ ... ]}.
    - You can "[quote] text from another person with {"[ ... ]}.
    - You can #[obselete] not anymore used sentences with {#[ ... ]}.

    < Design note >
        These symbols have been choosen because they are simple to access on a keyboard, refers to their effects and highlight plain text at different degrees.

    You can use all these decoration at the same time if you want. You just need to think to always close the last opened emphasis before the others.

    << .dash-+ >>

        "[*[Here] is an /[exemple].]

    <...>

    If you want to use a <purple>[custom] emphasis, use an header just before your <red>[emphasis].
    If the header is not handled in the output, it will be process like bold.

    << .dash-+ >>

        If you want to use a <purple>[custom] emphasis, use an header just <red>[before] your emphasis.

    <...>


<-> Links

    You can put links in your text by using {[content]>}.
    That link will use the adress provided by the next line beginning by {>: adress}.

    << .dash-+ >>
    
        [Link text]>

        >: http://www.google.com/

    <...>

    You can complete that syntax with a numeric index if you want to use an adress line not defined immediatly after, or used multiple times, or just be more explicit.

    << .dash-+ >>

        [Link text]>1 and [same link text]>1

        >1: http://www.google.com/

    <...>

    You can also indicate the adress directly on the link with {[content](adress)>}.

    << .dash-+ >>
    
        [Link text](http://www.google.com/)>

    <...>

    Those links can be external or internal. External links use a web adress or a file path as adress (like above). Internal links use any text as identifier. That identifier can be used as an internal adress somewhere in the document with {@(identifier)}.

    << .dash-+ >>
    
        [Link text]>

        >: target

        @(target) Targeted paragraph

    <...>
    << .dash-+ >>

        [Link text]>1 and [same link text]>1
    
        >1: target

        @(target) Targeted paragraph

    <...>
    << .dash-+ >>

        @(target) Targeted paragraph
    
        [Link text](target)>

    <...>

<-> Notes

    You can reference a note with {[content]*}.
    The referenced [note]* will be the next line beginning by {*: note}.
    If you use a number instead of {*}, it will reference the next note in text with [that number]1.

    *: Here is a first note.
    1: Here is a second note.

    << .dash- >>

        Here is [first note]* and here is a [second note]2.
        ...

        *: First note
        2: Second note

    <...>

    Like links, you can also inline the note with the following syntax: {[content](note)*}.

    << .dash-+ >>

        [WWW](World Wide Web)* is born at [CERN](Conseil Européen pour la Recherche Nucléaire)*.

    <...>

<-> Media

    If you want to insert a media (like a picture, a video or a table) or some text written in another language (like a code sample), you must use {{ ... }}.
    To indicate the type of media, it must be preceed by a block header providing the file extension used for this type of media. An extension must begin by a point {.}, like so: {< .ext >}

    < Design note >
    Supported media depend of your converter and its supported formats. Anyway, converted file must provide an alternative output if the media can't be displayed, like a link or a summary.

    If the media can be describe directly in your file with its own language, write it directly.

    << .dash- >>
        << .ext >>

        Here_is_another_language_using_underscores_as_spaces.

        <...>
    <...>

    < Design note >
        Try to use understandable languages when you describe directly your media. Dash is a plain-text oriented language and shouldn't contains binary data.

    If you don't indicate a file extension or if it is unknown and data isn't binary, media will be displayed as plain text.

    If the media that you want to display is inside a file, just provide the path.

    << .dash- >>

        < .ext > path/file.ext

    <...>

    You can also use prefix to force the kind of display in ambigous cases :

    - {+} will force converter to use its default graphic form
    - {-} will force converter to use its default textual form

    << .dash- >>

        ## Markdown is a plain-text document language like Dash

        ## Display with converter default representation
        < .md > # Markdown Title

        ## Display a title in a frame
        < .md+ > # Markdown Title

        ## Display "# Markdown Title" as Markdown language snippet
        < .md- > # Markdown Title

        ## gitignore is a language containing folder and file paths

        ## Display content of folder/.gitignore file
        < .gitignore > folder/.gitignore

        ## Display "folder/.gitignore" as gitignore language snippet
        < .gitignore- > folder/.gitignore

    <...>

    You can also combine both of them to display the textual and graphic form at the same time. It's ideal for a technical document showing examples. The order of signs will determine the order of display.

    << .dash- >>

        ## Display image then Markdown code
        < .md+- > ![Alternative text][img/logo.png]

        ## Display Markdown code then image
        < .md-+ > ![Alternative text][img/logo.png]

    <...>


    <--> Images

        < .dh-+ > { < .jpg > { http://www.gstatic.com/webp/gallery/1.jpg } }
        < .dh-+ > { < .png > { https://www.gstatic.com/webp/gallery3/1.png } }


    <--> Videos

        < .dh-+ > { < .mp4 > { http://www.sample-videos.com/video/mp4/720/big_buck_bunny_720p_1mb.mp4 } }
        < .dh-+ > { < .youtube.com > { hqW4qLcRD3w } }

    <--> Music sheet

        << .dash-+ >>
            << .abc >>

                DDAA|BBA2|

            <...>
        <...>

    <--> Tables

    << .dash-+ >>
        << .csv >>

            Name;John;Paul;Bob
            Age;22;34;58
            Happy?;Yes;Yes;No

        <...>
    <...>


    <--> Code

    << .dash-+ >>
        << .cs- >>

            int result = 3 + 4;
            System.Console.WriteLine("Result: " + result);

        <...>
    <...>


<-> Comments

    You can use comments by using {##} at the beginning of a line.
    For multiline comments, use {### ... ###}.

    << .dash-+ >>

        ## Here is a comment.

        ###
        Here is a comment block.
        On multiple lines.
        ###
        
    <...>

    < Design note >
        Some document output format can handle comments so they are not always ignoring.


<-> Notes

All notes can be displayed:

< .abc > { CDEF|GABc|defg }