OTP-8343 The documentation is now possible to build in an open source

environment after a number of bugs are fixed and some features are added in the documentation build process. - The arity calculation is updated. - The module prefix used in the function names for bif's are removed in the generated links so the links will look like http://www.erlang.org/doc/man/erlang.html#append_element-2 instead of http://www.erlang.org/doc/man/erlang.html#erlang:append_element-2 - Enhanced the menu positioning in the html documentation when a new page is loaded. - A number of corrections in the generation of man pages (thanks to Sergei Golovan) - Moved some man pages to more apropriate sections, pages in section 4 moved to 5 and pages in 6 moved to 7. - The legal notice is taken from the xml book file so OTP's build process can be used for non OTP applications.
erlang · Jan 26, 2010 · df88b47 · df88b47
1 parent 39ff2b4
commit df88b47
Show file tree

Hide file tree

Showing 112 changed files with 3,331 additions and 5,328 deletions.
diff --git a/Makefile.in b/Makefile.in
@@ -214,14 +214,15 @@ endif
 # ---------------------------------------------------------------
 # Target only used when building commercial ERTS patches
 # ---------------------------------------------------------------
-release_docs:
+release_docs docs:
 ifeq ($(OTP_SMALL_BUILD),true)
-	cd $(ERL_TOP)/lib  && $(MAKE) TESTROOT=$(RELEASE_ROOT) release_docs
+	cd $(ERL_TOP)/lib  && $(MAKE) TESTROOT=$(RELEASE_ROOT) $@
 else
-	cd $(ERL_TOP)/lib  && $(MAKE) BUILD_ALL=1 TESTROOT=$(RELEASE_ROOT) release_docs
-	cd $(ERL_TOP)/lib/dialyzer && $(MAKE) BUILD_ALL=1 TESTROOT=$(RELEASE_ROOT) release_docs
+	cd $(ERL_TOP)/lib  && $(MAKE) BUILD_ALL=1 TESTROOT=$(RELEASE_ROOT) $@
+	cd $(ERL_TOP)/lib/dialyzer && $(MAKE) BUILD_ALL=1 TESTROOT=$(RELEASE_ROOT) $@
 endif
-	cd $(ERL_TOP)/erts && $(MAKE) BUILD_ALL=1 TESTROOT=$(RELEASE_ROOT) release_docs
+	cd $(ERL_TOP)/erts && $(MAKE) BUILD_ALL=1 TESTROOT=$(RELEASE_ROOT) $@
+	cd $(ERL_TOP)/system/doc && $(MAKE) TESTROOT=$(RELEASE_ROOT) $@
 
 
 # ----------------------------------------------------------------------
@@ -730,6 +731,11 @@ bootstrap_nc_for_ne_no_debug_sym:
 #
 install: install.dirs install.emulator install.libs install.Install install.bin
 
+install-docs: 
+	ERL_TOP=$(ERL_TOP) INSTALLROOT=$(ERLANG_LIBDIR) PATH=$(BOOT_PREFIX)$${PATH} \
+	$(MAKE) RELEASE_ROOT=$(ERLANG_LIBDIR) release_docs
+
+
 install.emulator:
 	cd erts && \
 	  ERL_TOP=$(ERL_TOP) PATH=$(BOOT_PREFIX)$${PATH} \

diff --git a/erts/doc/src/erl.xml b/erts/doc/src/erl.xml
@@ -410,7 +410,7 @@
       <tag><c><![CDATA[-setcookie Cookie]]></c></tag>
       <item>
         <p>Sets the magic cookie of the node to <c><![CDATA[Cookie]]></c>, see
-          <seealso marker="erlang#erlang:set_cookie/2">erlang:set_cookie/2</seealso>.</p>
+          <seealso marker="erlang#set_cookie/2">erlang:set_cookie/2</seealso>.</p>
       </item>
       <tag><c><![CDATA[-shutdown_time Time]]></c></tag>
       <item>

diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml
@@ -4,7 +4,7 @@
 <cref>
   <header>
     <copyright>
-      <year>2001</year><year>2009</year>
+      <year>2001</year><year>2010</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -13,12 +13,12 @@
       compliance with the License. You should have received a copy of the
       Erlang Public License along with this software. If not, it can be
       retrieved online at http://www.erlang.org/.
-    
+
       Software distributed under the License is distributed on an "AS IS"
       basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
       the License for the specific language governing rights and limitations
       under the License.
-    
+
     </legalnotice>
 
     <title>erl_driver</title>
@@ -1292,7 +1292,7 @@ typedef struct ErlIOVec {
 	   has been set in the
 	   <seealso marker="driver_entry">driver_entry</seealso>,
 	   data can be forced into the driver via
-	   <seealso marker="erlang#erlang:port_command/3">port_command(Port, Data, [force])</seealso>
+	   <seealso marker="erlang#port_command/3">port_command(Port, Data, [force])</seealso>
 	   even though the driver has signaled that it is busy.
 	</p>
       </desc>

diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml
@@ -148,7 +148,7 @@ ok
            that the library needs in able to keep a state between NIF 
            calls. <c>enif_get_data()</c> will return this pointer.</p> 
         <p><c>load_info</c> is the second argument to <seealso
-           marker="erlang#erlang:load_nif-2">erlang:load_nif/2</seealso>.</p>
+           marker="erlang#load_nif-2">erlang:load_nif/2</seealso>.</p>
         <p>The library will fail to load if <c>load</c> returns
            anything other than 0. <c>load</c> can be NULL in case no
            initialization is needed.</p> 
@@ -397,7 +397,7 @@ typedef struct {
   </funcs>
   <section>
     <title>SEE ALSO</title>
-    <p><seealso marker="erlang#erlang:load_nif-2">load_nif(3)</seealso></p>
+    <p><seealso marker="erlang#load_nif-2">load_nif(3)</seealso></p>
   </section>
 </cref>
 
diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
diff --git a/erts/doc/src/notes.xml b/erts/doc/src/notes.xml
@@ -4,7 +4,7 @@
 <chapter>
   <header>
     <copyright>
-      <year>2004</year><year>2009</year>
+      <year>2004</year><year>2010</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -13,12 +13,12 @@
       compliance with the License. You should have received a copy of the
       Erlang Public License along with this software. If not, it can be
       retrieved online at http://www.erlang.org/.
-    
+
       Software distributed under the License is distributed on an "AS IS"
       basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
       the License for the specific language governing rights and limitations
       under the License.
-    
+
     </legalnotice>
 
     <title>ERTS Release Notes</title>
@@ -242,7 +242,7 @@
         <item>
           <p>
 	    The <seealso
-	    marker="erlang#erlang:port_command/3">erlang:port_command/3</seealso>
+	    marker="erlang#port_command/3">erlang:port_command/3</seealso>
 	    BIF has been added. <c>erlang:port_command/3</c> is
 	    currently not auto imported, but it is planned to be auto
 	    imported in OTP R14. For more information see the

diff --git a/erts/lib_src/Makefile.in b/erts/lib_src/Makefile.in
@@ -24,7 +24,6 @@ OMIT_OMIT_FP=no
 
 
 CC=@CC@
-GCC=@GCC@
 LD=@LD@
 AR=@AR@
 RANLIB=@RANLIB@
@@ -115,7 +114,7 @@ endif
 
 CREATE_DIRS=
 
-ifeq ($(GCC)-$(OMIT_FP),yes-true)
+ifeq ($(CC)-$(OMIT_FP), gcc-true)
 CFLAGS += -fomit-frame-pointer
 endif
 
@@ -484,6 +483,8 @@ ifneq ($(strip $(INTERNAL_RELEASE_LIBS)),)
 	$(INSTALL_DATA) $(INTERNAL_RELEASE_LIBS) $(RELSYSDIR)/lib/internal
 endif
 
+docs: 
+
 release_docs_spec:
 
 

diff --git a/lib/appmon/doc/src/Makefile b/lib/appmon/doc/src/Makefile
@@ -1,19 +1,19 @@
 #
 # %CopyrightBegin%
-# 
-# Copyright Ericsson AB 1997-2009. All Rights Reserved.
-# 
+#
+# Copyright Ericsson AB 1997-2010. All Rights Reserved.
+#
 # The contents of this file are subject to the Erlang Public License,
 # Version 1.1, (the "License"); you may not use this file except in
 # compliance with the License. You should have received a copy of the
 # Erlang Public License along with this software. If not, it can be
 # retrieved online at http://www.erlang.org/.
-# 
+#
 # Software distributed under the License is distributed on an "AS IS"
 # basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 # the License for the specific language governing rights and limitations
 # under the License.
-# 
+#
 # %CopyrightEnd%
 include $(ERL_TOP)/make/target.mk
 include $(ERL_TOP)/make/$(TARGET)/otp.mk
@@ -46,6 +46,9 @@ XML_CHAPTER_FILES = \
 
 BOOK_FILES = book.xml
 
+XML_FILES = $(BOOK_FILES) $(XML_APPLICATION_FILES) $(XML_REF3_FILES) \
+            $(XML_PART_FILES) $(XML_CHAPTER_FILES) 
+
 GIF_FILES = \
 	app_win.gif \
 	listbox_win.gif \

diff --git a/lib/common_test/doc/src/Makefile b/lib/common_test/doc/src/Makefile
@@ -1,19 +1,19 @@
 #
 # %CopyrightBegin%
-# 
-# Copyright Ericsson AB 2003-2009. All Rights Reserved.
-# 
+#
+# Copyright Ericsson AB 2003-2010. All Rights Reserved.
+#
 # The contents of this file are subject to the Erlang Public License,
 # Version 1.1, (the "License"); you may not use this file except in
 # compliance with the License. You should have received a copy of the
 # Erlang Public License along with this software. If not, it can be
 # retrieved online at http://www.erlang.org/.
-# 
+#
 # Software distributed under the License is distributed on an "AS IS"
 # basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 # the License for the specific language governing rights and limitations
 # under the License.
-# 
+#
 # %CopyrightEnd%
 #
 
@@ -112,18 +112,16 @@ DVIPS_FLAGS +=
 
 CT_SRC_DIR = $(ERL_TOP)/../internal_tools/common_test/src
 
-EDOC_ARGS=[{preprocess,true},{includes,["$(XMERL_DIR)/include","../../../test_server/include","../../include","../../../../erts/lib/kernel/include","../../../../lib/kernel/include","../../../../erts/lib/snmp/include","../../../../lib/snmp/include"]}]
-
-
 $(HTMLDIR)/%.gif: %.gif
 	$(INSTALL_DATA) $< $@
 
 docs: pdf html man
 
 $(CT_XML_FILES): 
-	erl -boot start_clean -noshell \
-	-eval 'docb_gen:module("../../src/$(@:%.xml=%.erl)",$(EDOC_ARGS))' \
-	-s erlang halt
+	escript $(DOCGEN)/priv/bin/xml_from_edoc.escript -preprocess true -i $(XMERL_DIR)/include \
+		-i ../../../test_server/include -i  ../../include \
+		-i ../../../../erts/lib/kernel/include -i ../../../../lib/kernel/include \
+		-i ../../../../erts/lib/snmp/include -i ../../../../lib/snmp/include ../../src/$(@:%.xml=%.erl)
 
 $(TOP_PDF_FILE): $(XML_FILES)
 

diff --git a/lib/crypto/doc/src/Makefile b/lib/crypto/doc/src/Makefile
@@ -42,6 +42,9 @@ XML_CHAPTER_FILES = notes.xml licenses.xml
 
 BOOK_FILES = book.xml
 
+XML_FILES = $(BOOK_FILES) $(XML_APPLICATION_FILES) $(XML_REF3_FILES)  $(XML_REF6_FILES) \
+            $(XML_PART_FILES) $(XML_CHAPTER_FILES) 
+
 GIF_FILES =
 
 # ----------------------------------------------------

diff --git a/lib/docbuilder/doc/src/inline_tags.xml b/lib/docbuilder/doc/src/inline_tags.xml
@@ -4,7 +4,7 @@
 <chapter>
   <header>
     <copyright>
-      <year>1997</year><year>2009</year>
+      <year>1997</year><year>2010</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -13,12 +13,12 @@
       compliance with the License. You should have received a copy of the
       Erlang Public License along with this software. If not, it can be
       retrieved online at http://www.erlang.org/.
-    
+
       Software distributed under the License is distributed on an "AS IS"
       basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
       the License for the specific language governing rights and limitations
       under the License.
-    
+
     </legalnotice>
 
     <title>Inline Tags</title>
@@ -157,7 +157,7 @@
     <p>The default behaviour can be modified by using the callback
       module option to <c>docb_transform:file/1,2</c> and defining a
       callback function
-      <seealso marker="docb_transform#Module:seealso/1">Module:seealso/1</seealso>.
+      <seealso marker="docb_transform#Module:seealso-1">Module:seealso/1</seealso>.
       This possibility is for example used in OTP to resolve cross
       references between applications.</p>
   </section>

diff --git a/lib/edoc/Makefile b/lib/edoc/Makefile
@@ -86,13 +86,13 @@ SYNTAX_TOOLS_DIR=$(ERL_TOP)/lib/syntax_tools
 XMERL_DIR=$(ERL_TOP)/lib/xmerl
 INCDIR=$(XMERL_DIR)/include
 
-docs:
+# The overriding docs target have been removed so the default make rules work properly.
+
+edocs:
 	erl -noshell -pa $(BINDIR) -pa $(SYNTAX_TOOLS_DIR)/ebin \
 	    -pa $(XMERL_DIR)/ebin -run edoc_run application \
 	    "'$(APPNAME)'" '"."' '$(DOC_OPTS)'
 
-edocs: docs
-
 info:
 	@echo $(HTML_FILES)
 

diff --git a/lib/edoc/doc/src/Makefile b/lib/edoc/doc/src/Makefile
@@ -103,11 +103,10 @@ html: gifs $(HTML_REF_MAN_FILE)
 man: $(MAN3_FILES)
 
 $(XML_REF3_FILES):
-	docb_gen -def vsn $(EDOC_VSN) -includes $(INC_DIR) \
-		$(SRC_DIR)/$(@:%.xml=%.erl)
+	escript $(DOCGEN)/priv/bin/xml_from_edoc.escript -def vsn $(EDOC_VSN) -i $(ERL_TOP)/lib/edoc/include $(SRC_DIR)/$(@:%.xml=%.erl)
 
 $(XML_CHAPTER_FILES):
-	docb_gen -chapter -def vsn $(EDOC_VSN) ../overview.edoc
+	escript $(DOCGEN)/priv/bin/xml_from_edoc.escript -def vsn $(EDOC_VSN) -chapter ../overview.edoc
 
 gifs: $(GIF_FILES:%=$(HTMLDIR)/%)
 

diff --git a/lib/edoc/src/Makefile b/lib/edoc/src/Makefile
@@ -55,6 +55,8 @@ all: $(OBJECTS)
 
 $(OBJECTS): $(HRL_FILES) $(XMERL)/include/xmerl.hrl
 
+docs: 
+
 clean:
 	rm -f $(OBJECTS) edoc_parser.erl
 	rm -f core *~

diff --git a/lib/erl_docgen/priv/bin/Makefile b/lib/erl_docgen/priv/bin/Makefile
@@ -1,19 +1,19 @@
 #
 # %CopyrightBegin%
-# 
-# Copyright Ericsson AB 2009. All Rights Reserved.
-# 
+#
+# Copyright Ericsson AB 2009-2010. All Rights Reserved.
+#
 # The contents of this file are subject to the Erlang Public License,
 # Version 1.1, (the "License"); you may not use this file except in
 # compliance with the License. You should have received a copy of the
 # Erlang Public License along with this software. If not, it can be
 # retrieved online at http://www.erlang.org/.
-# 
+#
 # Software distributed under the License is distributed on an "AS IS"
 # basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 # the License for the specific language governing rights and limitations
 # under the License.
-# 
+#
 # %CopyrightEnd%
 #
 #
@@ -38,7 +38,8 @@ RELSYSDIR = $(RELEASE_PATH)/lib/erl_docgen-$(VSN)
 
 
 ESCRIPT_FILES= \
-	codeline_preprocessing.escript
+	codeline_preprocessing.escript \
+	xml_from_edoc.escript
 
 # ----------------------------------------------------
 # FLAGS

diff --git a/lib/erl_docgen/priv/bin/codeline_preprocessing.escript b/lib/erl_docgen/priv/bin/codeline_preprocessing.escript
@@ -1,20 +1,20 @@
 #!/usr/bin/env escript
 %% -*- erlang -*-
 %% %CopyrightBegin%
-%% 
-%% Copyright Ericsson AB 2009. All Rights Reserved.
-%% 
+%%
+%% Copyright Ericsson AB 2009-2010. All Rights Reserved.
+%%
 %% The contents of this file are subject to the Erlang Public License,
 %% Version 1.1, (the "License"); you may not use this file except in
 %% compliance with the License. You should have received a copy of the
 %% Erlang Public License along with this software. If not, it can be
 %% retrieved online at http://www.erlang.org/.
-%% 
+%%
 %% Software distributed under the License is distributed on an "AS IS"
 %% basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 %% the License for the specific language governing rights and limitations
 %% under the License.
-%% 
+%%
 %% %CopyrightEnd%
 %%----------------------------------------------------------------------
 %% File    : codeline_preprocessing.escript
@@ -54,13 +54,16 @@ main([InFile, OutFile]) ->
 main(_) ->
     usage().
 
+%%======================================================================
+%% Internal functions
+%%======================================================================
 
 %%----------------------------------------------------------------------
-%% Function: main/1
+%% Function: usage/0
 %% Description:
 %%----------------------------------------------------------------------
 usage() ->
-    io:format("usage:  codeline_preprocessing <infile> <outfile>\n"),
+    io:format("usage:  codeline_preprocessing.escript <infile> <outfile>\n"),
     halt(1).
-Original file line number
+Diff line change
@@ Expand Up / @@ -55,6 +55,8 @@ all: $(OBJECTS) @@
     $(OBJECTS): $(HRL_FILES) $(XMERL)/include/xmerl.hrl
+    docs:
     clean:
     	rm -f $(OBJECTS) edoc_parser.erl
     	rm -f core *~
@@ Expand Down @@