Merge branch 'lukas/kernel/code-chunk-lookup/OTP-16494/OTP-16222/OTP-…

…16406/OTP-16499/OTP-16500/OTP-16501/OTP-16502/OTP-16503' * lukas/kernel/code-chunk-lookup/OTP-16494/OTP-16222/OTP-16406/OTP-16499/OTP-16500/OTP-16501/OTP-16502/OTP-16503: (27 commits) otp: Update doc build instructions with DOC_TARGETS Include erts in travis dialyzer run erts: Fix unmatched return dialyzer warning Move chunk into erlang module for speed Update primary bootstrap Add DOC_TARGETS makefile variable Start work on documentation for EEP-48 Remove term_to_binary of doc chunks doc content Use <code> for monospace, remove anno, add <a marker> Insert newline before paragraph if the previous element did not Generate hidden chunk files for any internal modules Implement EEP-48 aka doc chunks doc: Move typer cli app to REF1 section otp: Refactor doc make system and introduce EEP-48 Fix docs to handle chunk generation Fix mnesia docs to use common name convention Fix ssh type doc to use common name convention Fix ssl doc to use a single name convention Add Module prefix to all callbacks docgen: Remove many dead entities from dtds ...
erlang · Feb 24, 2020 · dd3b015 · dd3b015
2 parents 912db35 + 1befa3c
commit dd3b015
Show file tree

Hide file tree

Showing 177 changed files with 3,031 additions and 7,252 deletions.
diff --git a/.gitignore b/.gitignore
@@ -185,6 +185,8 @@ JAVADOC-GENERATED
 /lib/*/doc/pdf/*.pdf
 /lib/*/doc/src/*.fo
 /lib/*/doc/xml/*.xml
+/lib/*/doc/xml/*.ent
+/lib/*/doc/chunks/*.chunk
 
 /lib/config.log
 /lib/config.status
@@ -283,6 +285,8 @@ JAVADOC-GENERATED
 /erts/doc/pdf/*.pdf
 /erts/doc/src/*.fo
 /erts/doc/xml/*.xml
+/erts/doc/xml/figures/*.png
+/erts/doc/chunks/*.chunk
 /erts/doc/man[0-9]/*.[0-9]
 /erts/doc/CONF_INFO
 

diff --git a/.travis.yml b/.travis.yml
@@ -36,7 +36,24 @@ matrix:
       script:
         - ./scripts/build-otp
         - ./scripts/run-dialyzer
-
+    # Doc build second as it also takes a long time to run
+    - env: Linux64Docbuild
+      script:
+        - ./scripts/build-otp docs
+      deploy:
+        provider: pages
+        repo: erlang/cd
+        target-branch: master
+        skip-cleanup: true
+        keep-history: false
+        verbose: true
+        github-token: $ERLANG_CD_GITHUB_TOKEN
+        on:
+          # We only deploy on pushes to branches
+          all_branches: true
+          tags: false
+          condition: $TRAVIS_PULL_REQUEST = "false"
+          repo: erlang/otp
     - env: Linux32
       services:
         - docker
@@ -91,23 +108,6 @@ matrix:
             - xsltproc
             - libxml2-utils
 
-    - env: Linux64Docbuild
-      script:
-        - ./scripts/build-otp docs
-      deploy:
-        provider: pages
-        repo: erlang/cd
-        target-branch: master
-        skip-cleanup: true
-        keep-history: false
-        verbose: true
-        github-token: $ERLANG_CD_GITHUB_TOKEN
-        on:
-          # We only deploy on pushes to branches
-          all_branches: true
-          tags: false
-          condition: $TRAVIS_PULL_REQUEST = "false"
-          repo: erlang/otp
     # This stage publishes a otp bundle that contains multiple
     # Erlang/OTP source repositories
     - stage: deploy

diff --git a/HOWTO/INSTALL.md b/HOWTO/INSTALL.md
@@ -217,6 +217,12 @@ Build the documentation.
 
     $ make docs
 
+It is possible to limit which types of documentation is build by passing the `DOC_TARGETS`
+environment variable to `make docs`. The currently available types are: `html`, `pdf`, `man` and
+`chunks`. Example:
+
+    $ make docs DOC_TARGETS=chunks
+
 #### Build Issues ####
 
 We have sometimes experienced problems with Oracle's `java` running out of
@@ -247,6 +253,8 @@ or using the `release_docs` target.
 
         $ make release_docs RELEASE_ROOT=<release dir>
 
+It is possible to limit which types of documentation is released using the same `DOC_TARGETS`
+environment variable as when building documentation.
 
 ### Accessing the Documentation ###
 
@@ -261,6 +269,8 @@ After installation you can access the documentation by
 *   Browsing the html pages by loading the page `/usr/local/lib/erlang/doc/erlang/index.html`
     or `<BaseDir>/lib/erlang/doc/erlang/index.html` if the prefix option has been used.
 
+*   Read the embedded documentation by using the built-in shell functions `h/1,2,3` or
+    `ht/1,2,3`.
 
 ### How to Install the Pre-formatted Documentation ###
 

diff --git a/bootstrap/lib/kernel/include/eep48.hrl b/bootstrap/lib/kernel/include/eep48.hrl
@@ -0,0 +1,14 @@
+-define(NATIVE_FORMAT,<<"application/erlang+html">>).
+-define(CURR_DOC_VERSION, {1,0,0}).
+-record(docs_v1, {anno,
+                  beam_language = erlang,
+                  format = ?NATIVE_FORMAT,
+                  module_doc,
+                  metadata = #{ otp_doc_vsn => ?CURR_DOC_VERSION },
+                  docs}).
+
+-record(docs_v1_entry, {kind_name_arity,
+                        anno,
+                        signature,
+                        doc,
+                        metadata}).
diff --git a/bootstrap/lib/stdlib/ebin/shell_docs.beam b/bootstrap/lib/stdlib/ebin/shell_docs.beam
diff --git a/erts/doc/Makefile b/erts/doc/Makefile
diff --git a/erts/doc/src/.gitignore b/erts/doc/src/.gitignore
@@ -0,0 +1,3 @@
+ref_man.xml
+specs.xml
+part.xml
diff --git a/erts/doc/src/Makefile b/erts/doc/src/Makefile
@@ -37,15 +37,15 @@ RELSYSDIR = $(RELEASE_PATH)/$(APPLICATION)-$(VSN)
 # Target Specs
 # ----------------------------------------------------
 XML_APPLICATION_FILES = ref_man.xml
-XML_REF1_FILES = epmd.xml \
-	erl.xml \
-	erlc.xml \
-	escript.xml \
-	werl.xml \
-	erlsrv.xml \
-	start_erl.xml \
-	run_erl.xml \
-	start.xml
+XML_REF1_FILES = epmd_cmd.xml \
+	erl_cmd.xml \
+	erlc_cmd.xml \
+	escript_cmd.xml \
+	werl_cmd.xml \
+	erlsrv_cmd.xml \
+	start_erl_cmd.xml \
+	run_erl_cmd.xml \
+	start_cmd.xml
 
 ifeq ($(USE_ESOCK), yes)
 XML_REF3_ESOCK_EFILES = socket.xml
@@ -72,13 +72,16 @@ XML_REF3_EFILES = \
 	zlib.xml \
 	$(XML_REF3_ESOCK_EFILES)
 
-XML_REF3_FILES = \
-	$(XML_REF3_EFILES) \
+XML_REF3_CREF = \
 	driver_entry.xml \
 	erl_nif.xml \
 	erl_driver.xml \
 	erts_alloc.xml
 
+XML_REF3_FILES = \
+	$(XML_REF3_EFILES) \
+	$(XML_REF3_CREF)
+
 XML_PART_FILES = \
 	part.xml internal.xml
 
@@ -96,7 +99,6 @@ XML_INTERNAL_FILES = \
 	SuperCarrier.xml        \
 	CountingInstructions.xml
 
-
 XML_CHAPTER_FILES = \
 	introduction.xml \
 	tty.xml \
@@ -118,32 +120,24 @@ TOPDOCDIR=../../../doc
 
 BOOK_FILES = book.xml
 
-GIF_FILES = \
+IMAGE_FILES = \
 	erl_ext_fig.gif
 
 XML_FILES = \
 	$(BOOK_FILES) $(XML_CHAPTER_FILES) \
 	$(XML_PART_FILES) $(XML_REF3_FILES) $(XML_REF1_FILES) $(XML_APPLICATION_FILES)
 
+HTML_EXTRA_FILES = $(ERL_TOP)/erts/example/time_compat.erl \
+	$(ERL_TOP)/lib/kernel/examples/gen_tcp_dist/src/gen_tcp_dist.erl
+
 XML_GEN_FILES = $(XML_INTERNAL_FILES:%=$(XMLDIR)/%)
 
-# ----------------------------------------------------
+NO_CHUNKS = $(XML_REF3_CREF) erl_tracer.xml
 
-HTML_FILES = $(XML_APPLICATION_FILES:%.xml=$(HTMLDIR)/%.html) \
-	$(XML_PART_FILES:%.xml=$(HTMLDIR)/%.html)
+# ----------------------------------------------------
 
-INFO_FILE     = ../../info
 INFO_FILE_SRC = ../../info.src
 
-MAN1_FILES = $(XML_REF1_FILES:%.xml=$(MAN1DIR)/%.1)
-MAN3_FILES = $(XML_REF3_FILES:%.xml=$(MAN3DIR)/%.3)
-
-HTML_REF_MAN_FILE = $(HTMLDIR)/index.html
-
-TOP_PDF_FILE = $(PDFDIR)/$(APPLICATION)-$(VSN).pdf
-
-SPECS_FILES = $(XML_REF3_EFILES:%.xml=$(SPECDIR)/specs_%.xml)
-
 TOP_SPECS_FILE = specs.xml
 
 XML_FIGURE_DIR = $(XMLDIR)/figures
@@ -152,61 +146,25 @@ INTERNAL_DOC_PNG_FILES = $(wildcard ../../emulator/internal_doc/figures/*.png)
 PNG_FILES = $(notdir $(INTERNAL_DOC_PNG_FILES))
 XMLDIR_PNG_FILES = $(PNG_FILES:%=$(XML_FIGURE_DIR)/%)
 
-# ----------------------------------------------------
-# FLAGS
-# ----------------------------------------------------
-XML_FLAGS +=
-
-KERNEL_SRC=$(ERL_TOP)/lib/kernel/src
-KERNEL_INCLUDE=$(ERL_TOP)/lib/kernel/include
-SPECS_FLAGS = -I$(KERNEL_SRC) -I$(KERNEL_INCLUDE)
-
 # ----------------------------------------------------
 # Targets
 # ----------------------------------------------------
-_create_dirs := $(shell mkdir -p $(XML_FIGURE_DIR))
+include $(ERL_TOP)/make/doc.mk
 
-$(HTMLDIR)/%.gif: %.gif
-	$(INSTALL_DATA) $< $@
+_create_dirs := $(shell mkdir -p $(XML_FIGURE_DIR))
 
 $(XML_FIGURE_DIR)/%.png: ../../emulator/internal_doc/figures/%.png
 	$(INSTALL_DATA) $< $@
 
-docs: part ref_man specs figures man pdf html $(INFO_FILE)
-
-$(TOP_PDF_FILE): $(XML_FILES)
-
-pdf: $(TOP_PDF_FILE)
-
-html: gifs $(HTML_REF_MAN_FILE)
-
-man: $(MAN1_FILES) $(MAN3_FILES)
-
-ref_man: ref_man.xml
-part: part.xml
-specs: specs.xml
-
-gifs: $(GIF_FILES:%=$(HTMLDIR)/%)
+html: figures
 
 $(INFO_FILE): $(INFO_FILE_SRC) $(ERL_TOP)/make/$(TARGET)/otp.mk
 	sed -e 's;%RELEASE%;$(SYSTEM_VSN);' $(INFO_FILE_SRC) > $(INFO_FILE)
 
 figures: $(XMLDIR_PNG_FILES)
 
-debug opt:
-
-ldocs: xmllint local_docs
-
-clean:
-	rm -rf $(HTMLDIR)/*
-	rm -rf $(XMLDIR)
-	rm -f $(MAN1DIR)/*
-	rm -f $(MAN3DIR)/*
-	rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo)
-	rm -f $(SPECDIR)/*
-	rm -f errs core *~
-
-$(SPECDIR)/specs_%.xml:
+## This rule generate dummy specs for all XML_REF3_CREF's
+$(XML_REF3_CREF:%.xml=$(SPECDIR)/specs_%.xml): $(@:%.xml=%.xml)
 	$(gen_verbose)escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) \
                 -o$(dir $@) -module $(patsubst $(SPECDIR)/specs_%.xml,%,$@)
 
@@ -229,25 +187,10 @@ specs.xml: specs.xml.src
 # ----------------------------------------------------
 # Release Target
 # ----------------------------------------------------
-include $(ERL_TOP)/make/otp_release_targets.mk
 
-release_docs_spec: docs
-	$(INSTALL_DIR) "$(RELSYSDIR)/doc/pdf"
-	$(INSTALL_DATA) $(TOP_PDF_FILE) "$(RELSYSDIR)/doc/pdf"
-	$(INSTALL_DIR) "$(RELSYSDIR)/doc/html"
+release_html_spec: release_figures
+
+release_figures:
 	$(INSTALL_DIR) "$(RELSYSDIR)/doc/html/figures"
-	$(INSTALL_DATA) $(HTMLDIR)/* \
-		"$(RELSYSDIR)/doc/html"
 	$(INSTALL_DATA) $(XMLDIR)/figures/* \
 		"$(RELSYSDIR)/doc/html/figures"
-	$(INSTALL_DATA) $(ERL_TOP)/erts/example/time_compat.erl \
-		"$(RELSYSDIR)/doc/html"
-	$(INSTALL_DATA) $(ERL_TOP)/lib/kernel/examples/gen_tcp_dist/src/gen_tcp_dist.erl \
-		"$(RELSYSDIR)/doc/html"
-	$(INSTALL_DATA) $(INFO_FILE) "$(RELSYSDIR)"
-	$(INSTALL_DIR) "$(RELEASE_PATH)/man/man3"
-	$(INSTALL_DATA) $(MAN3DIR)/* "$(RELEASE_PATH)/man/man3"
-	$(INSTALL_DIR) "$(RELEASE_PATH)/man/man1"
-	$(INSTALL_DATA) $(MAN1_FILES) "$(RELEASE_PATH)/man/man1"
-
-release_spec:
diff --git a/erts/doc/src/epmd.xml → erts/doc/src/epmd_cmd.xml b/erts/doc/src/epmd.xml → erts/doc/src/epmd_cmd.xml
@@ -11,19 +11,19 @@
       Licensed under the Apache License, Version 2.0 (the "License");
       you may not use this file except in compliance with the License.
       You may obtain a copy of the License at
- 
+
           http://www.apache.org/licenses/LICENSE-2.0
 
       Unless required by applicable law or agreed to in writing, software
       distributed under the License is distributed on an "AS IS" BASIS,
       WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
       See the License for the specific language governing permissions and
       limitations under the License.
-    
+
     </legalnotice>
 
     <title>epmd</title>
-    <prepared>Claes Wikstr&ouml;m</prepared>    
+    <prepared>Claes Wikstr&ouml;m</prepared>
     <responsible></responsible>
     <docno>1</docno>
     <approved></approved>
@@ -295,9 +295,8 @@
     <title>Logging</title>
     <p>On some operating systems <em>syslog</em> will be used for
       error reporting when <c>epmd</c> runs as a daemon. To enable
-      the error logging, you must edit the
-      <path unix="" windows="">/etc/syslog.conf</path> file and add an
-      entry:</p>
+      the error logging, you must edit the /etc/syslog.conf file and
+      add an entry:</p>
 
     <code type="none"><![CDATA[
   !epmd
@@ -334,5 +333,3 @@
     <p>To restrict access further, firewall software must be used.</p>
   </section>
 </comref>
-
-