Auto merge of #27789 - chriskrycho:remove_pandoc_references, r=steveklabnik

Per @steveklabnik's comment [here](rust-lang/cargo#739 (comment)), the Pandoc components of the Makefile are no longer used, and as such the corresponding components of the documentation are out of date.

  - I've removed the Pandoc (and therefore also LaTeX) elements of the makefile and confirmed that the build proceeds correctly.
  - I updated the documentation to reference `rustdoc` and  of Pandoc.

r? @steveklabnik

Author: bors

mk/docs.mk

@@ -13,9 +13,6 @@
 #
 # The DOCS variable is their names (with no file extension).
 #
-# PDF_DOCS lists the targets for which PDF documentation should be
-# build.
-#
 # RUSTDOC_FLAGS_xyz variables are extra arguments to pass to the
 # rustdoc invocation for xyz.
 #
@@ -35,8 +32,6 @@ DOCS += guide-crates guide-error-handling guide-ffi guide-macros guide \
     guide-testing
 
 
-PDF_DOCS := reference
-
 RUSTDOC_DEPS_reference := doc/full-toc.inc
 RUSTDOC_FLAGS_reference := --html-in-header=doc/full-toc.inc
 
@@ -52,13 +47,6 @@ RUSTDOC_HTML_OPTS_NO_CSS = --html-before-content=doc/version_info.html \
 
 RUSTDOC_HTML_OPTS = $(RUSTDOC_HTML_OPTS_NO_CSS) --markdown-css rust.css
 
-PANDOC_BASE_OPTS := --standalone --toc --number-sections
-PANDOC_TEX_OPTS = $(PANDOC_BASE_OPTS) --from=markdown --to=latex \
-	--include-before-body=doc/version.tex \
-	--include-before-body=doc/footer.tex \
-	--include-in-header=doc/uptack.tex
-PANDOC_EPUB_OPTS = $(PANDOC_BASE_OPTS) --to=epub
-
 # The rustdoc executable...
 RUSTDOC_EXE = $(HBIN2_H_$(CFG_BUILD))/rustdoc$(X_$(CFG_BUILD))
 # ...with rpath included in case --disable-rpath was provided to
@@ -89,30 +77,10 @@ else
 HTML_DEPS :=
 endif
 
-# Check for xelatex
-
-ifneq ($(CFG_XELATEX),)
-    CFG_LATEX := $(CFG_XELATEX)
-    XELATEX = 1
-  else
-    $(info cfg: no xelatex found, disabling LaTeX docs)
-    NO_PDF_DOCS = 1
-endif
-
-ifeq ($(CFG_PANDOC),)
-$(info cfg: no pandoc found, omitting PDF and EPUB docs)
-ONLY_HTML_DOCS = 1
-endif
-
-
 ######################################################################
 # Rust version
 ######################################################################
 
-doc/version.tex: $(MKFILE_DEPS) $(wildcard $(D)/*.*) | doc/
-	@$(call E, version-stamp: $@)
-	$(Q)echo "$(CFG_VERSION)" >$@
-
 HTML_DEPS += doc/version_info.html
 doc/version_info.html: $(D)/version_info.html.template $(MKFILE_DEPS) \
                        $(wildcard $(D)/*.*) | doc/
@@ -121,10 +89,10 @@ doc/version_info.html: $(D)/version_info.html.template $(MKFILE_DEPS) \
                 s/SHORT_HASH/$(CFG_SHORT_VER_HASH)/; \
                 s/STAMP/$(CFG_VER_HASH)/;" $< >$@
 
-GENERATED += doc/version.tex doc/version_info.html
+GENERATED += doc/version_info.html
 
 ######################################################################
-# Docs, from rustdoc and sometimes pandoc
+# Docs from rustdoc
 ######################################################################
 
 doc/:
@@ -150,20 +118,6 @@ doc/footer.inc: $(D)/footer.inc | doc/
 	$(Q)cp -PRp $< $@ 2> /dev/null
 
 # The (english) documentation for each doc item.
-
-define DEF_SHOULD_BUILD_PDF_DOC
-SHOULD_BUILD_PDF_DOC_$(1) = 1
-endef
-$(foreach docname,$(PDF_DOCS),$(eval $(call DEF_SHOULD_BUILD_PDF_DOC,$(docname))))
-
-doc/footer.tex: $(D)/footer.inc | doc/
-	@$(call E, pandoc: $@)
-	$(CFG_PANDOC) --from=html --to=latex $< --output=$@
-
-doc/uptack.tex: $(D)/uptack.tex | doc/
-	$(Q)cp $< $@
-
-# HTML (rustdoc)
 DOC_TARGETS += doc/not_found.html
 doc/not_found.html: $(D)/not_found.md $(HTML_DEPS) | doc/
 	@$(call E, rustdoc: $@)
@@ -179,47 +133,6 @@ doc/$(1).html: $$(D)/$(1).md $$(HTML_DEPS) $$(RUSTDOC_DEPS_$(1)) | doc/
 	@$$(call E, rustdoc: $$@)
 	$$(Q)$$(RUSTDOC) $$(RUSTDOC_HTML_OPTS) $$(RUSTDOC_FLAGS_$(1)) $$<
 
-ifneq ($(ONLY_HTML_DOCS),1)
-
-# EPUB (pandoc directly)
-DOC_TARGETS += doc/$(1).epub
-doc/$(1).epub: $$(D)/$(1).md | doc/
-	@$$(call E, pandoc: $$@)
-	$$(CFG_PANDOC) $$(PANDOC_EPUB_OPTS) $$< --output=$$@
-
-# PDF (md =(pandoc)=> tex =(pdflatex)=> pdf)
-DOC_TARGETS += doc/$(1).tex
-doc/$(1).tex: $$(D)/$(1).md doc/uptack.tex doc/footer.tex doc/version.tex | doc/
-	@$$(call E, pandoc: $$@)
-	$$(CFG_PANDOC) $$(PANDOC_TEX_OPTS) $$< --output=$$@
-
-ifneq ($(NO_PDF_DOCS),1)
-ifeq ($$(SHOULD_BUILD_PDF_DOC_$(1)),1)
-DOC_TARGETS += doc/$(1).pdf
-ifneq ($(XELATEX),1)
-doc/$(1).pdf: doc/$(1).tex
-	@$$(call E, latex compiler: $$@)
-	$$(Q)$$(CFG_LATEX) \
-	-interaction=batchmode \
-	-output-directory=doc \
-	$$<
-else
-# The version of xelatex on the snap bots seemingly ingores -output-directory
-# So we'll output to . and move to the doc directory manually.
-# This will leave some intermediate files in the build directory.
-doc/$(1).pdf: doc/$(1).tex
-	@$$(call E, latex compiler: $$@)
-	$$(Q)$$(CFG_LATEX) \
-	-interaction=batchmode \
-	-output-directory=. \
-	$$<
-	$$(Q)mv ./$(1).pdf $$@
-endif # XELATEX
-endif # SHOULD_BUILD_PDF_DOCS_$(1)
-endif # NO_PDF_DOCS
-
-endif # ONLY_HTML_DOCS
-
 endef
 
 $(foreach docname,$(DOCS),$(eval $(call DEF_DOC,$(docname))))

src/doc/README.md

@@ -1,11 +1,5 @@
 # Rust documentations
 
-## Dependencies
-
-[Pandoc](http://johnmacfarlane.net/pandoc/installing.html), a universal
-document converter, is required to generate docs as HTML from Rust's
-source code.
-
 ## Building
 
 To generate all the docs, just run `make docs` from the root of the repository.
@@ -26,15 +20,12 @@ To generate an HTML version of a doc from Markdown manually, you can do
 something like:
 
 ~~~~
-pandoc --from=markdown --to=html5 --number-sections -o reference.html reference.md
+rustdoc reference.md
 ~~~~
 
 (`reference.md` being the Rust Reference Manual.)
 
-The syntax for pandoc flavored markdown can be found at:
-
-- http://johnmacfarlane.net/pandoc/README.html#pandocs-markdown
-
-A nice quick reference (for non-pandoc markdown) is at:
+An overview of how to use the `rustdoc` command is available [in the docs][1].
+Further details are available from the command line by with `rustdoc --help`.
 
-- http://kramdown.gettalong.org/quickref.html
+[1]: https://github.com/rust-lang/rust/blob/master/src/doc/trpl/documentation.md