← Back to branch summary

~ubuntu-branches/ubuntu/trusty/libtext-markdown-perl/trusty

« back to all changes in this revision

Viewing changes to README

  • Committer: Bazaar Package Importer
  • Author(s): Ansgar Burchardt
  • Date: 2008-07-24 21:06:58 UTC
  • mfrom: (1.1.1 upstream)
  • Revision ID: james.westby@ubuntu.com-20080724210658-kbpqulb200ddijqe
Tags: 1.0.21-1
* New upstream release.
  + Update pod_name patch accordingly
* Install Todo as documentation
* Refresh debian/rules for debhelper 7
* Add myself to Uploaders.
* debian/control: Use dist-based URL for Homepage field
* Update debian/copyright:
  + Adopt to current proposed format
  + Replace "Copyright" and "(C)" by "©"
  + Include full license text as the version in
    /usr/share/common-licenses/BSD refers to the University as copyright
    holder
  + Move pointer to GPL and Artistic license to the right section

Show diffs side-by-side

added added

removed removed

Lines of Context:
README
1
1
NAME
2
 
    Text::MultiMarkdown - Convert MultiMarkdown syntax to (X)HTML
 
2
    Text::Markdown - Convert Markdown syntax to (X)HTML
3
3
 
4
4
SYNOPSIS
5
 
        use Text::MultiMarkdown 'markdown';
 
5
        use Text::Markdown 'markdown';
6
6
        my $html = markdown($text);
7
7
 
8
 
        use Text::MultiMarkdown 'markdown';
 
8
        use Text::Markdown 'markdown';
9
9
        my $html = markdown( $text, {
10
10
            empty_element_suffix => '>',
11
11
            tab_width => 2,
12
 
            use_wikilinks => 1,
13
12
        } );
14
13
 
15
 
        use Text::MultiMarkdown;
16
 
        my $m = Text::MultiMarkdown->new;
 
14
        use Text::Markdown;
 
15
        my $m = Text::Markdown->new;
17
16
        my $html = $m->markdown($text);
18
17
 
19
 
        use Text::MultiMarkdown;
 
18
        use Text::Markdown;
20
19
        my $m = Text::MultiMarkdown->new(
21
20
            empty_element_suffix => '>',
22
21
            tab_width => 2,
23
 
            use_wikilinks => 1,
24
22
        );
25
23
        my $html = $m->markdown( $text );
26
24
 
36
34
    HTML tags (like <div> and <table> as well).
37
35
 
38
36
SYNTAX
39
 
    For more information about Markdown's syntax, see:
 
37
    This module implements the 'original' Markdown markdown syntax from:
40
38
 
41
39
        http://daringfireball.net/projects/markdown/
42
 
    
43
 
    This module implements MultiMarkdown, which is an extension to
44
 
    Markdown..
45
 
 
46
 
    This is documented at:
47
 
 
48
 
    http://michelf.com/projects/php-markdown/extra/
49
 
 
50
 
    and
51
 
 
52
 
    http://fletcherpenney.net/MultiMarkdown/
53
 
 
54
 
    This documentation is going to be moved/copied into this module for
55
 
    clearer reading in a future release..
56
40
 
57
41
OPTIONS
58
 
    MultiMarkdown supports a number of options to it's processor which
 
42
    Text::Markdown supports a number of options to it's processor which
59
43
    control the behavior of the output document.
60
44
 
61
45
    These options can be supplied to the constructor, on in a hash with the
64
48
 
65
49
    The options for the processor are:
66
50
 
67
 
    use_metadata
68
 
        Controls the metadata options below.
69
 
 
70
 
    strip_metadata
71
 
        Not implemented yet.
72
 
 
73
51
    empty element suffix
74
52
        This option can be used to generate normal HTML output. By default,
75
53
        it is ' />', which is xHTML, change to '>' for normal HTML.
76
54
 
77
 
    img_ids
78
 
        Controls if <img> tags generated have an id attribute. Defaults to
79
 
        true. Turn off for compatibility with the original markdown.
80
 
 
81
 
    heading_ids
82
 
        Controls if <hX> tags generated have an id attribute. Defaults to
83
 
        true. Turn off for compatibility with the original markdown.
84
 
 
85
 
    bibliography_title
86
 
        The title of the generated bibliography, defaults to 'Bibliography'.
87
 
 
88
55
    tab_width
89
56
        Controls indent width in the generated markup, defaults to 4
90
57
 
91
 
    A number of possible items of metadata can also be supplied as options.
92
 
    Note that if the use_metadata is true then the metadata in the document
93
 
    will overwrite the settings on command line.
94
 
 
95
 
    Metadata options supported are:
96
 
 
97
 
    document_format
98
 
    use_wikilinks
99
 
    base_url
100
 
 
101
 
METADATA
102
 
    MultiMarkdown supports the concept of 'metadata', which allows you to
103
 
    specify a number of formatting options within the document itself.
104
 
    Metadata should be placed in the top few lines of a file, on value per
105
 
    line as colon separated key/value pairs. The metadata should be
106
 
    separated from the document with a blank line.
107
 
 
108
 
    Most metadata keys are also supported as options to the constructor, or
109
 
    options to the markdown method itself. (Note, as metadata, keys contain
110
 
    space, whereas options the keys are underscore separated.)
111
 
 
112
 
    You can attach arbitrary metadata to a document, which is output in HTML
113
 
    <META> tags if unknown, see t/11document_format.t for more info.
114
 
 
115
 
    A list of 'known' metadata keys, and their effects are listed below:
116
 
 
117
 
    document format
118
 
        If set to 'complete', MultiMarkdown will render an entire xHTML
119
 
        page, otherwise it will render a document fragment
120
 
 
121
 
        css Sets a CSS file for the file, if in 'complete' document format.
122
 
 
123
 
        title
124
 
            Sets the page title, if in 'complete' document format.
125
 
 
126
 
    use wikilinks
127
 
        If set to '1' or 'on', causes links that are WikiWords to
128
 
        automatically be processed into links.
129
 
 
130
 
    base url
131
 
        This is the base URL for referencing wiki pages. In this is not
132
 
        supplied, all wiki links are relative.
133
 
 
134
 
METHODS
135
 
    new A very simple constructor.
136
 
 
137
 
    markdown
138
 
        The main function as far as the outside world is concerned. See the
139
 
        SYNOPSIS for details on use.
140
 
 
141
 
    _Markdown
142
 
        The main function (internal use only).
143
 
 
144
 
    Header2Label
145
 
        Internal use only.
146
 
 
147
 
    xhtmlMetaData
148
 
        Internal use only.
149
 
 
150
 
    textMetaData
151
 
        Internal use only.
152
 
 
153
 
NOTICE
154
 
    Warning: this code is messy and does not adhere to any consistent set of
155
 
    code guidelines; this is not because of the original quality of the
156
 
    code, which is far above what I can pretend to be capable of creating,
157
 
    but because of the various patching and diffing steps in between and the
158
 
    incomplete translation of the original code into a module.
 
58
    markdown_in_html_blocks
 
59
        Controls if Markdown is processed when inside HTML blocks. Defaults
 
60
        to 0.
 
61
 
 
62
METHODS
 
63
METHODS
 
64
  new
 
65
    A simple constructor, see the SYNTAX and OPTIONS sections for more
 
66
    information.
 
67
 
 
68
  markdown
 
69
    The main function as far as the outside world is concerned. See the
 
70
    SYNOPSIS for details on use.
 
71
 
 
72
  urls
 
73
    Returns a reference to a hash with the key being the markdown reference
 
74
    and the value being the URL.
 
75
 
 
76
    Useful for building scripts which preprocess a list of links before the
 
77
    main content. See t/05options.t for an example of this hashref being
 
78
    passed back into the markdown method to create links.
 
79
 
 
80
OTHER IMPLEMENTATIONS
 
81
    Markdown has been re-implemented in a number of languages, and with a
 
82
    number of additions.
 
83
 
 
84
    Those that I have found are listed below:
 
85
 
 
86
    C - <http://www.pell.portland.or.us/~orc/Code/discount>
 
87
        Discount - Original Markdown, but in C. Fastest implementation
 
88
        available, and passes MDTest. Adds it's own set of custom features.
 
89
 
 
90
    python - <http://www.freewisdom.org/projects/python-markdown/>
 
91
        Python Markdown which is mostly compatible with the original, with
 
92
        an interesting extension API.
 
93
 
 
94
    ruby (maruku) - <http://maruku.rubyforge.org/>
 
95
        One of the nicest implementations out there. Builds a parse tree
 
96
        internally so very flexible.
 
97
 
 
98
    php - <http://michelf.com/projects/php-markdown/>
 
99
        A direct port of Markdown.pl, also has a separately maintained
 
100
        'extra' version, which adds a number of features that were borrowed
 
101
        by MultiMarkdown.
 
102
 
 
103
    lua - <http://www.frykholm.se/files/markdown.lua>
 
104
        Port to lua. Simple and lightweight (as lua is).
 
105
 
 
106
    haskell - <http://johnmacfarlane.net/pandoc/>
 
107
        Pandoc is a more general library, supporting Markdown,
 
108
        reStructuredText, LaTeX and more.
 
109
 
 
110
    javascript - <http://www.attacklab.net/showdown-gui.html>
 
111
        Direct(ish) port of Markdown.pl to JavaScript
159
112
 
160
113
BUGS
161
 
    To file bug reports or feature requests (other than topics listed in the
162
 
    Caveats section above) please send email to:
163
 
 
164
 
        support@daringfireball.net (for Markdown issues)
165
 
 
166
 
        fletcher@freeshell.org (for MultiMarkdown issues)
167
 
 
168
 
        kulp@cpan.org, bobtfish@bobtfish.net (for Text::MultiMarkdown issues)
169
 
 
 
114
    To file bug reports or feature requests please send email to:
 
115
 
 
116
        bug-Text-Markdown@rt.cpan.org
 
117
    
170
118
    Please include with your report: (1) the example input; (2) the output
171
119
    you expected; (3) the output Markdown actually produced.
172
120
 
184
132
        http://fletcher.freeshell.org/
185
133
 
186
134
        CPAN Module Text::MultiMarkdown (based on Text::Markdown by Sebastian
187
 
        Riedel) by Darren Kulp & Tomas Doran
188
 
        http://kulp.ch/ & http://www.bobtfish.net/
 
135
        Riedel) originally by Darren Kulp (http://kulp.ch/)
 
136
    
 
137
        This module is maintained by: Tomas Doran http://www.bobtfish.net/
 
138
 
 
139
THIS DISTRIBUTION
 
140
    Please note that this distribution is a fork of John Gruber's original
 
141
    Markdown project, and it *is not* in any way blessed by him.
 
142
 
 
143
    Whilst this code aims to be compatible with the original Markdown.pl
 
144
    (and incorporates and passes the Markdown test suite) whilst fixing a
 
145
    number of bugs in the original - there may be differences between the
 
146
    behavior of this module and Markdown.pl. If you find any differences
 
147
    where you believe Text::Markdown behaves contrary to the Markdown spec,
 
148
    please report them as bugs.
 
149
 
 
150
    Text::Markdown *does not* extend the markdown dialect in any way from
 
151
    that which is documented at daringfireball. If you want additional
 
152
    features, you should look at Text::MultiMarkdown.
189
153
 
190
154
COPYRIGHT AND LICENSE
191
155
    Original Code Copyright (c) 2003-2004 John Gruber
195
159
    <http://fletcher.freeshell.org/> All rights reserved.
196
160
 
197
161
    Text::MultiMarkdown changes Copyright (c) 2006-2008 Darren Kulp
198
 
    <http://kulp.ch> and Tomas Doran <bobtfish@bobtfish.net>
 
162
    <http://kulp.ch> and Tomas Doran <http://www.bobtfish.net>
199
163
 
200
164
    Redistribution and use in source and binary forms, with or without
201
165
    modification, are permitted provided that the following conditions are