Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: cleanups #12783

Merged
merged 5 commits into from
Mar 11, 2014
Merged

doc: cleanups #12783

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
862aced
doc: remove node.js dependency
adrientetar Mar 9, 2014
9eadcac
doc: have a real switch b/w LaTeX compilers
adrientetar Mar 9, 2014
7979ae5
doc: CSS fixes
adrientetar Mar 9, 2014
7ec1eb8
doc: auto-generate LaTeX includes
adrientetar Mar 9, 2014
840a270
doc: remove outdated tutorial entry, restore removed Makefile entries
adrientetar Mar 9, 2014
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 2 additions & 3 deletions configure
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -455,9 +455,8 @@ probe CFG_ISCC iscc
probe CFG_LLNEXTGEN LLnextgen
probe CFG_PANDOC pandoc
probe CFG_PDFLATEX pdflatex
probe CFG_XETEX xetex
probe CFG_LUATEX luatex
probe CFG_NODE nodejs node
probe CFG_XELATEX xelatex
probe CFG_LUALATEX lualatex
probe CFG_GDB gdb
if [ "$CFG_OSTYPE" = "unknown-linux-gnu" ]
then
Expand Down
61 changes: 28 additions & 33 deletions mk/docs.mk
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,9 +27,9 @@
# translated.
######################################################################
DOCS := index tutorial guide-ffi guide-macros guide-lifetimes \
guide-tasks guide-container guide-pointers \
complement-cheatsheet guide-runtime \
rust rustdoc
guide-tasks guide-container guide-pointers guide-testing \
guide-runtime complement-bugreport complement-cheatsheet \
complement-lang-faq complement-project-faq rust rustdoc

PDF_DOCS := tutorial rust

Expand All @@ -46,7 +46,7 @@ RUSTDOC_HTML_OPTS = --markdown-css rust.css \
--markdown-in-header=doc/favicon.inc --markdown-after-content=doc/footer.inc

PANDOC_BASE_OPTS := --standalone --toc --number-sections
PANDOC_TEX_OPTS = $(PANDOC_BASE_OPTS) --include-before-body=doc/version.md \
PANDOC_TEX_OPTS = $(PANDOC_BASE_OPTS) --include-before-body=doc/version.tex \
--from=markdown --include-before-body=doc/footer.tex --to=latex
PANDOC_EPUB_OPTS = $(PANDOC_BASE_OPTS) --to=epub

Expand All @@ -73,18 +73,20 @@ endif
# Check for the various external utilities for the EPUB/PDF docs:

ifeq ($(CFG_PDFLATEX),)
$(info cfg: no pdflatex found, omitting doc/rust.pdf)
NO_PDF_DOCS = 1
else
ifeq ($(CFG_XETEX),)
$(info cfg: no xetex found, disabling doc/rust.pdf)
NO_PDF_DOCS = 1
$(info cfg: no pdflatex found, deferring to xelatex)
ifeq ($(CFG_XELATEX),)
$(info cfg: no xelatex found, deferring to lualatex)
ifeq ($(CFG_LUALATEX),)
$(info cfg: no lualatex found, disabling LaTeX docs)
NO_PDF_DOCS = 1
else
CFG_LATEX := $(CFG_LUALATEX)
endif
else
ifeq ($(CFG_LUATEX),)
$(info cfg: lacking luatex, disabling pdflatex)
NO_PDF_DOCS = 1
endif
CFG_LATEX := $(CFG_XELATEX)
endif
else
CFG_LATEX := $(CFG_PDFLATEX)
endif


Expand All @@ -93,17 +95,12 @@ $(info cfg: no pandoc found, omitting PDF and EPUB docs)
ONLY_HTML_DOCS = 1
endif

ifeq ($(CFG_NODE),)
$(info cfg: no node found, omitting PDF and EPUB docs)
ONLY_HTML_DOCS = 1
endif


######################################################################
# Rust version
######################################################################

doc/version.md: $(MKFILE_DEPS) $(wildcard $(D)/*.*) | doc/
doc/version.tex: $(MKFILE_DEPS) $(wildcard $(D)/*.*) | doc/
@$(call E, version-stamp: $@)
$(Q)echo "$(CFG_VERSION)" >$@

Expand All @@ -115,10 +112,10 @@ doc/version_info.html: $(D)/version_info.html.template $(MKFILE_DEPS) \
$(CFG_VER_HASH) | head -c 8)/;\
s/STAMP/$(CFG_VER_HASH)/;" $< >$@

GENERATED += doc/version.md doc/version_info.html
GENERATED += doc/version.tex doc/version_info.html

######################################################################
# Docs, from rustdoc and sometimes pandoc & node
# Docs, from rustdoc and sometimes pandoc
######################################################################

doc/:
Expand All @@ -143,10 +140,6 @@ doc/footer.inc: $(D)/footer.inc | doc/
@$(call E, cp: $@)
$(Q)cp -a $< $@ 2> /dev/null

doc/footer.tex: $(D)/footer.tex | doc/
@$(call E, cp: $@)
$(Q)cp -a $< $@ 2> /dev/null

# The (english) documentation for each doc item.

define DEF_SHOULD_BUILD_PDF_DOC
Expand All @@ -168,22 +161,24 @@ ifneq ($(ONLY_HTML_DOCS),1)
DOC_TARGETS += doc/$(1).epub
doc/$(1).epub: $$(D)/$(1).md | doc/
@$$(call E, pandoc: $$@)
$$(Q)$$(CFG_NODE) $$(D)/prep.js --highlight $$< | \
$$(CFG_PANDOC) $$(PANDOC_EPUB_OPTS) --output=$$@
$$(CFG_PANDOC) $$(PANDOC_EPUB_OPTS) $$< --output=$$@

doc/footer.tex: $(D)/footer.inc | doc/
@$$(call E, pandoc: $$@)
$$(CFG_PANDOC) --from=html --to=latex $$< --output=$$@

# PDF (md =(pandoc)=> tex =(pdflatex)=> pdf)
DOC_TARGETS += doc/$(1).tex
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does prep.js --highlight really have zero effect?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes because prep.js outputs its own HTML directives which pandoc cannot recognize.
You can see it as the PDF doc has never been highlighted as of now.

Note that if we were to add the .rust class to snippets, we could probably use pandoc's native highlighting capatibilities i.e. Kate (here is an example of that).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you put that specific information in the commit message and/or PR description so that someone looking at the gist history knows why this change happened?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated.

doc/$(1).tex: $$(D)/$(1).md doc/footer.tex doc/version.md | doc/
doc/$(1).tex: $$(D)/$(1).md doc/footer.tex doc/version.tex | doc/
@$$(call E, pandoc: $$@)
$$(Q)$$(CFG_NODE) $$(D)/prep.js $$< | \
$$(CFG_PANDOC) $$(PANDOC_TEX_OPTS) --output=$$@
$$(CFG_PANDOC) $$(PANDOC_TEX_OPTS) $$< --output=$$@

ifneq ($(NO_PDF_DOCS),1)
ifeq ($$(SHOULD_BUILD_PDF_DOC_$(1)),1)
DOC_TARGETS += doc/$(1).pdf
doc/$(1).pdf: doc/$(1).tex
@$$(call E, pdflatex: $$@)
$$(Q)$$(CFG_PDFLATEX) \
@$$(call E, latex compiler: $$@)
$$(Q)$$(CFG_LATEX) \
-interaction=batchmode \
-output-directory=doc \
$$<
Expand Down
8 changes: 2 additions & 6 deletions src/doc/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,6 @@
document converter, is required to generate docs as HTML from Rust's
source code.

[Node.js](http://nodejs.org/) is also required for generating HTML from
the Markdown docs (reference manual, tutorials, etc.) distributed with
this git repository.

[po4a](http://po4a.alioth.debian.org/) is required for generating translated
docs from the master (English) docs.

Expand All @@ -30,8 +26,8 @@ rustdoc --output-dir html-doc/ --output-format html ../src/libstd/path.rs

# Additional notes

To generate an HTML version of a doc from Markdown without having Node.js
installed, you can do something like:
To generate an HTML version of a doc from Markdown manually, you can do
something like:

~~~~
pandoc --from=markdown --to=html5 --number-sections -o rust.html rust.md
Expand Down
7 changes: 0 additions & 7 deletions src/doc/footer.tex
View file
Open in desktop

This file was deleted.

146 changes: 0 additions & 146 deletions src/doc/lib/codemirror-node.js
View file
Open in desktop

This file was deleted.

Loading