The Project Gutenberg RST Manual
Marcello Perathoner · 영어
"The Project Gutenberg RST Manual"은 디지털 시대의 문학 보존을 위한 실용적인 지침서입니다.
번역은 아직 없습니다. 아래 번역 요청으로 일정을 앞당길 수 있어요.
Pagera 서평
"The Project Gutenberg RST Manual"은 디지털 시대의 문학 보존을 위한 실용적인 지침서입니다. 전자책 제작의 표준 형식이 된 reStructuredText(RST)를 활용하여 프로젝트 구텐베르크 스타일의 전자책을 만드는 방법을 상세히 안내합니다. 단순히 기술적인 매뉴얼을 넘어, 문학 작품을 영구히 보존하고 공유하고자 하는 열정을 불러일으키는 매력적인 여정으로 독자를 초대합니다. 전자책 제작에 관심 있는 사람이라면 누구나 쉽게 따라 할 수 있도록 친절하게 구성되어 있습니다.
저자
Marcello Perathoner
마르첼로 페라토너는 구텐베르크 프로젝트 RST 매뉴얼을 집필한 작가입니다. 구체적인 생몰년도와 국적은 알려져 있지 않으며, 해당 매뉴얼을 통해 구텐베르크 프로젝트의 텍스트 서식 지정에 기여했습니다. 그의 작업은 디지털 텍스트 보존 및 접근성에 중요한 역할을 했습니다.
The Project Gutenberg RST Manual
Marcello Perathoner · 영어
"The Project Gutenberg RST Manual"은 디지털 시대의 문학 보존을 위한 실용적인 지침서입니다.
목차
전문
원문 (영어)
Contents
Installing EpubMaker
Windows
Debian
PG-RST Classes
Classes For Inline Text
Classes For Block Text
Classes For Front Matter Markup
PG-RST Extensions
Styles
Pagination
Table of Contents
List of Figures
List of Tables
Toc-Entry
Footnotes
Page Numbers
Dropcaps
Tables
PG Metadata
Top Boilerplate
Metadata Directive
Bottom Boilerplate
PG-RST Best Practices
Examples and Tests
Section 3.1
Section 3.2
Section 3.3
[pg!v]
List of Tables
- Classes For Inline Text I
- Classes For Inline Text II
- Classes For Inline Text III
- Classes For Block Text
- Classes For Front Matter Markup
- Directives For Pagination
- Footnote Positions
- Support for dropcaps in output formats
- Demo Table
- Truth table for “and”
- Fields In the PG Scheme
- Fields In the DC Scheme
- Fields In the MARCREL Scheme
- Fields Without Scheme
- TABLE 8 Types of Computers Used in the Systems Reported
[pg!vii]
Installing EpubMaker
EpubMaker is Project Gutenberg’s file converter. It can convert from PG-RST to HTML, EPUB, PDF and plain text.
Windows
Prerequisites
Install Python.
Assuming you don’t have python yet. If you have either version 2.6 or 2.7 already installed, skip this.
From http://www.python.org/download/releases/2.7/ download the Windows x86 MSI Installer (2.7) and run it.
Select all the default options and install.
Install Python Setuptools.
From http://pypi.python.org/pypi/setuptools download setuptools-0.6c11.win32-py2.7.exe (or any newer version) and run it.
If you are using python 2.6 get the setuptools for 2.6.
Install Groff. (You can skip this step if you don’t want to generate plain text files.)
From http://gnuwin32.sourceforge.net/packages/groff.htm download Complete package, except sources - Setup (groff-1.20.1-setup.exe) and run it.
Select all the default options and install.
Install TexLive. (You can skip this step if you don’t want to generate PDF files.)
Go to http://mirror.ctan.org/systems/texlive/tlnet and download the file install-tl.zip. Then say:
> unzip install-tl.zip > cd install-tl* > install-tlThis will open the TeX Live installation wizard. Follow the instructions. When in doubt use the defaults.
This will take quite a while. (3 hours on an old Dell Vostro 1000 laptop. It installs about 2.5 GB in 93,000 files.) If you experience download problems, restart the wizard: it will resume the download where it left off.
Long installation instructions can be found at http://www.tug.org/texlive/doc/texlive-en/texlive-en.html#x1-150003
Install HTML Tidy. (You can skip this step if you only want to process RST files and don’t want to build EPUBs from HTML input.)
If you are a post-processor you already have this.
http://tidy.sourceforge.net/
Update your PATH.
Start | Control Panel | System | Advanced | Environment Variables. Click "Path" in the User variables at the top. Click "Edit"
If the field is empty just enter (all in one line):
C:\Python27; C:\Python27\Scripts; C:\Program Files\GnuWin32\bin;If the field contains data, go to the end of that data and add a semicolon if there isn’t one already and then add the string above.
Click Ok three times.
EpubMaker
At the command prompt run:
> easy_install epubmakerTest your installation:
> epubmaker --help > epubmaker https://www.gutenberg.org/masters/rst/181/181.rst
Debian
Prerequisites
(Does not work with python 3 yet. If your distribution uses python 3 as default (not likely!), you’ll have to parallel install python 2.6 or 2.7.)
# apt-get install python python-setuptools python-lxml # apt-get install groff tidy # apt-get install libpng-dev libjpeg-dev libfreetype6-devNote: To get PDF generation to work, you have to use TeX Live version 2009-11 or newer. You can get those from debian testing or unstable. If don’t want to switch from debian stable, you have to install TeX Live manually.
If you are on testing or unstable:
# apt-get install texlive texlive-latex-extra texlive-xetex # apt-get install ttf-linux-libertine ttf-dejavuElse, to install TeX Live manually, go to http://mirror.ctan.org/systems/texlive/tlnet and download the file install-tl-unx.tar.gz. Unpack it. Then:
# cd /path/where/unpacked # perl install-tl -guiLong installation instructions can be found at http://www.tug.org/texlive/doc/texlive-en/texlive-en.html#x1-150003
EpubMaker
# easy_install epubmakerKindlegen
(Optional: Used only to make Kindle files):
$ wget http://s3.amazonaws.com/kindlegen/kindlegen_linux_2.6_i386_v1.2.tar.gz $ tar -xzf kindlegen_linux_2.6_i386_v1.2.tar.gzPG-RST Classes
A list of classes you can use in PG-RST.
Classes For Inline Text
These classes have an effect on inline text. If you put them on a block, all inline contents of the block will be rendered accordingly.
Classes For Inline Text IClass
Explanation
italics
Switch to italic font.
bold
Switch to boldface.
small-caps
Switch to small capitals.
gesperrt
Switch to gesperrt (extended letter spacing).
antiqua
Switch to antiqua.
monospaced
Switch to monospaced font.
Classes For Inline Text IIClass
Explanation
smaller
Switch to smaller font.
larger
Switch to larger font.
xx-small
Switch to smallest font.
x-small
Switch to very small font.
small
Switch to small font.
medium
Switch to normal font size.
large
Switch to large font.
x-large
Switch to very large font.
xx-large
Switch to largest font.
Classes For Inline Text IIIClass
Explanation
red
Switch to red font.
green
Switch to green font.
blue
Switch to blue font.
yellow
Switch to yellow font.
white
Switch to white font.
gray
Switch to gray font.
black
Switch to black font.
Classes For Block Text
These classes have an effect on block text. Please do not confuse the alignment of the block with the alignment of the text in the block. Eg. a table can be centered, while the text inside the table is left-aligned. The alignment of the block is set with the align option.
Classes For Block TextClass
Explanation
left
Left-aligns the text in the block.
center
Centers the text in the block.
right
Right-aligns the text in the block.
justify
Justifies the text in the block.
white-space-pre-line
Preserves newlines.
Classes For Front Matter Markup
EpubMaker includes a few classes to markup front matter. While it is not necessary to do this, it adds value. In future the PG catalog might automatically extract not only the cover page but also the title page, verso, etc.
Classes For Front Matter MarkupClass
Explanation
coverpage
The cover page.
frontispiece
The frontispiece.
titlepage
The title page.
verso
The title page verso.
dedication
The dedication page.
plainpage
A general class for page.
Use these classes on a container. These classes already insert page breaks before the container so you need not insert page breaks on your own.
PG-RST Extensions
You can create custom roles based on the existing ones. This is how you create and then use custom roles.
This text is in Small Caps.
You can attach more than one class to a role:
This text is big and bold.
Styles
You can redefine the rendering of elements:
Now emphasis will be rendered as gesperrt.
And Strong Emphasis will be rendered as small-caps.
And Strong Emphasis will be rendered as big bold small-caps.
literally red
super
Hamlet and Othello.
You can semantically markup foreign text:
Pas de double is the French for "father of twins".
Pagination
Pagination is important if you generate PDFs. See the Directives For Pagination Table.
Table of Contents
Use the RST contents directive to automatically generate a table of contents.
N.B. You may also provide a table of contents manually.
In PG-RST the contents directive requires you to specify an argument or the local option.
The local option displays a local table of contents, containing only the sub-sections of the section in which it is declared.
The page-numbers option displays the original page number in the TOC.
A TOC With Page Numbers
Installing EpubMaker
Windows
Debian
PG-RST Classes
Classes For Inline Text
Classes For Block Text
Classes For Front Matter Markup
PG-RST Extensions
Styles
Pagination
Table of Contents
List of Figures
List of Tables
Toc-Entry
Footnotes
Page Numbers
Dropcaps
Tables
PG Metadata
Top Boilerplate
Metadata Directive
Bottom Boilerplate
PG-RST Best Practices
Examples and Tests
Section 3.1
Section 3.2
Section 3.3
List of Figures
Use the lof directive to generate a list of figures automatically.
N.B. You may also provide a list of figures manually.
A List of Figures
- Richard and Drucilla Martin
List of Tables
Use the lot directive to generate a list of tables.
N.B. You may also provide a list of tables manually.
A List of Tables
- Classes For Inline Text I
- Classes For Inline Text II
- Classes For Inline Text III
- Classes For Block Text
- Classes For Front Matter Markup
- Directives For Pagination
- Footnote Positions
- Support for dropcaps in output formats
- Demo Table
- Truth table for “and”
- Fields In the PG Scheme
- Fields In the DC Scheme
- Fields In the MARCREL Scheme
- Fields Without Scheme
- TABLE 8 Types of Computers Used in the Systems Reported
Toc-Entry
Use the toc-entry directive to:
provide an alternate toc entry
suppress a toc entry, or
switch toc gathering on or off.
A toc-entry with argument sets the argument as toc entry for the next section, figure or table.
A toc-entry without argument suppresses the toc entry for the next section, figure or table.
Use the depth option to set the depth up to which section titles are gathered for the toc. A depth of 0 switches toc gathering off.
Footnotes
Always define footnotes right after the paragraph they are referenced.
Positioning of footnotesFormat
Position
HTML
Collected under the footnotes directive.
EPUB
Idem.
TXT
Where they are defined.
At the bottom of the current page.
To collect the footnotes use the footnotes directive. This directive will output a section with title and all footnotes in the document will be moved inside the section.
In PDF and TXT formats the footnotes directive will do nothing.1
Test23 .
Page Numbers
The sequence [pg n] will convert into a page number marker of n. n can be any arabic or roman numeral. The sequence itself will be removed from the text flow leaving a page anchor. There must be spaces around the sequence. If the page break is in the middle of a word, join the word and put the sequence at the end of the word.
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt [pg 42] ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores [pg xviii] et ea rebum.
A reference to a page number can be inserted with the sequence [pg n]_. This will generate a link to the page anchor.
See page [pg 42]_.
An invisible page number can be inserted with the sequence [pg!n].
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt [pg!43] ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. See page [pg 43]_.
See page [pg iii]_.
Dropcaps
You can insert dropcaps with the dropcap directive. You can use either an enlarged character or an image as dropcap. You can also specify a span of character that should be set in small-caps after the dropcap initial.
Support for dropcaps in output formatsFormat
Letter
Image
HTML
enlarged and dropped
resized and dropped
EPUB
enlarged on baseline
resized on baseline
TXT
normal size
alt text
enlarged and dropped5
resized and dropped5
The first argument (mandatory) states the character(s) to replace with caps. It must match the beginning of the next paragraph.
The second (optional) argument states the characters to replace with small-caps. It must also match the beginning of the next paragraph.
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.
The lines option (PDF only) specifies how many lines the dropcap should span. Default is 2.
The indents option (PDF only) can specifiy up to 2 length values. The first one is the indent of the first line, the second one the indent of the following lines. The indent is calculated from the right border of the dropcap letter. Defaults are 0em and 0.5em.
The image option specifies the image url. In plain text and EPUB the image will not be used.
Tables
Be careful with tables because the table support of many ereaders is weak or nil.
Tables also support these options:
widthMakes the table that wide.
widthsA space-separated list of unitless values, each specifying the relative width of one table column.
If you don’t use the option widths, the column widths are calculated from the layout of the table in your source file.
alignsHorizontally align the columns.
A space-separated list of alignments, each specifying the alignment of one column.
Valid alignments values are: left, center, right and justify.
vertical-alignsVertically align the columns.
A space-separated list of vertical alignments, each specifying the alignment of one column.
Valid alignments values are: top, middle, and bottom.
Note: vertical alignment is fully supported in HTML only. Other formats may support it in varying degrees.
summary (HTML only.)Puts a summary attribute on the table element.
These are the extra classes supported by PG-RST:
norulesOmits the rules between table rows. (Not the rule between header and body nor the rules at the top and bottom of the table.)
Use this class when the eye can follow the table rows without the aid of rules.
Header row, column 1 (header rows optional)
Justified
Centered
Price ($)
row 1
column
column
1.23
row 2
col col col col col col col
col
45.67
row 3
Cells may span columns. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam sed diam voluptua. At vero eos accusam et justo duo dolores et rebum.
Cells may span rows and columns. Lorem ipsum dolor sit amet, consetetur adipiscing.
Cells may span rows.
row 4
row 5
A
B
A and B
False
False
False
True
False
False
False
True
False
True
True
True
PG Metadata
Top Boilerplate
This section explains the PG boilerplate that you must put at the top of your PG-RST file.
It looks like this:
Insert this line verbatim. It must be the first line in the text.6 This tells the converter to use UTF-8 encoding and is also recognized by many editors.
The metadata directive: see section below.
This will be the first line of the generated files. It should say: “The Project Gutenberg Ebook of Title” or just “Title”. Use ’=’ above and below the title.
This directive inserts the PG header as generated from the metadata.
Metadata Directive
The metadata directive contains all data that is used to generate the PG header and the PG catalog entry.
The scheme is the part before the dot.
PG Scheme
The PG scheme holds data that is relevant to Project Gutenberg only.
DC Scheme
This scheme holds standard Dublincore stuff and is used by many search engines and the PG cataloguing software.
MARCREL Scheme
This is used to record contributors to the text. All these fields may appear more than once. Don’t put more than one name into one field. Repeat the field if necessary.
No Scheme
Some fields are associated with none of the above schemes.
Bottom Boilerplate
You must put this at the very bottom of your PG-RST file.
This directive inserts the PG footer and license.
PG-RST Best Practices
Images
Specify a width option in images and a figwidth option in figures and express it in percent.
If you don’t specify a width, the converter will calculate the width percentile for you, using the formula:
image_width / (980px * 0.8) * 100(980px is the approx. wide of a browser window with scrollbar on a 1024px wide screen, 0.8 are 10% margins left and right.)
Expressing the image size relative to the screen width is the best way to get images right on a wide variety of devices form iPhones to print.
Drucilla Martin was a slave in Giles County, Tennessee.
The legend consists of all elements after the caption. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum.
[pg!2]
Tests and Examples
Notice
The rest of this file contains tests. You may look at the RST source to learn how things are done.
A generated local table of contents:
Section 3.1
Section 3.2
Section 3.3
A local table of contents as highlights:
Kingston — Instructive remarks on early English history — Instructive observations on carved oak and life in general — Sad case of Stivvings, junior — Musings on antiquity — I forget that I am steering — Interesting result — Hampton Court Maze — Harris as a guide.
ÄÖÜ äöüß Æsop Œdipus cœr. Đ. †‡ ｳ. §2.1
‘’ ‚‛ “ ” ‹› em — en –.
“ ‘Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.’ ”
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. [pg 3] At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.
――――
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.
[pg 4]
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.
And now a quote by Lorem Ipsum:
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita [pg 5] kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.
―― Lorem Ipsum
[pg 7]
Section 3.1
I pity the man who can travel from Dan to Beersheba, and say “’Tis all barren;” and so is all the world to him who will not cultivate the fruits it offers.
―― Sterne: Sentimental Journey.
Simple List with hyphens
Wash left ear.
Wash right ear.
Brush teeth.
Simple List with bullets
Wash left ear.
Wash right ear.
Brush teeth.
Nested List
Item 1.
Item 1a.
Item 1b.
Item 1.a.I
Item 1.a.II
Item 1.a.III
Item 1.a.IV
Item 2.A.i [pg 8]
Item 2.A.ii
Item 2.B.i
Item 2.B.ii
Item 2.B.iii
Item 2.C
Item 3.
Definition List
termDefinition.
term 2Definition 2
Definition 2 paragraph 2.
long term 3Definition 3
Option List (not used by PG)
-acommand-line option "a"
-1 file, --one=file, --two fileMultiple options with arguments.
[pg 123]
Section 3.27
Some text so this section isn’t empty.
Section 3.3
THE MAN WHO PLEASES.
The dearest friend to me, the kindest man,The best-conditioned and unwearied spiritIn doing courtesies.―― Merchant of Venice.
He hath a daily beauty in his life.―― Othello.
Such a man would win any woman in the worldif a’ could get her good will.―― Much Ado About Nothing.
There are few subjects of deeper interest to men and women than that of personal fascination,
TABLE 8 Types of Computers Used in the Systems Reported«Ora si comincia per quelli di fuori e per quelli di dentro a far grandissima e crudel guerra.»
Istorie pistolesi.
Type
Number
ASI 210
1
(3)
ASI 2100
2
CDC 160A
2
(3)
CDC 3100
1
total computer cost 0.22 ± 0.06 by averaging ------------------------ = 0.23 -> separate ratios for each cost of bare accelerator system[pg!10]
Footnotes
Not even print the section title.
[3]Later editions continued as follows:
Gibbon test. A footnote inside a footnote.
[6]A unicode BOM is allowed before this. In fact most Windows editors will add a BOM without asking you.
[7]This title contains a footnote reference. The footnote reference will not show up in the TOC.
[pg 99]
Transcriber’s Note
Minor spelling errors have been silently corrected.
Hyphenation has been made consistent.
Pagera 서평
"The Project Gutenberg RST Manual"은 디지털 시대의 문학 보존을 위한 실용적인 지침서입니다. 전자책 제작의 표준 형식이 된 reStructuredText(RST)를 활용하여 프로젝트 구텐베르크 스타일의 전자책을 만드는 방법을 상세히 안내합니다. 단순히 기술적인 매뉴얼을 넘어, 문학 작품을 영구히 보존하고 공유하고자 하는 열정을 불러일으키는 매력적인 여정으로 독자를 초대합니다. 전자책 제작에 관심 있는 사람이라면 누구나 쉽게 따라 할 수 있도록 친절하게 구성되어 있습니다.
저자
Marcello Perathoner
마르첼로 페라토너는 구텐베르크 프로젝트 RST 매뉴얼을 집필한 작가입니다. 구체적인 생몰년도와 국적은 알려져 있지 않으며, 해당 매뉴얼을 통해 구텐베르크 프로젝트의 텍스트 서식 지정에 기여했습니다. 그의 작업은 디지털 텍스트 보존 및 접근성에 중요한 역할을 했습니다.
번역 현황
대기로그인 후 번역을 요청하실 수 있습니다.
자주 묻는 질문
네, 완전히 무료입니다. 이 책은 저작권이 만료된 퍼블릭 도메인 도서라 회원가입·결제 없이 바로 읽을 수 있습니다. Pagera는 광고 수익으로 운영됩니다.
독서·어학에 도움이 되는 상품
이 포스팅은 쿠팡 파트너스 활동의 일환으로, 이에 따른 일정액의 수수료를 제공받습니다.
무료 이용 안내
회원가입 없이도 바로 읽기를 시작할 수 있습니다. 더 많은 열람과 기능은 회원 가입 후 이용하세요.