From df88b47cdafcc2e04452456942ea572a7b72e2f2 Mon Sep 17 00:00:00 2001 From: Lars G Thorsen Date: Tue, 26 Jan 2010 10:13:35 +0000 Subject: 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. --- lib/erl_docgen/priv/bin/Makefile | 13 +- .../priv/bin/codeline_preprocessing.escript | 17 +- lib/erl_docgen/priv/bin/xml_from_edoc.escript | 149 ++++++++++++ lib/erl_docgen/priv/xsl/db_eix.xsl | 68 +++++- lib/erl_docgen/priv/xsl/db_html.xsl | 251 +++++++++++++++------ lib/erl_docgen/priv/xsl/db_man.xsl | 180 ++++++++++----- lib/erl_docgen/priv/xsl/db_pdf.xsl | 99 ++++++-- lib/erl_docgen/priv/xsl/db_pdf_params.xsl | 26 ++- 8 files changed, 631 insertions(+), 172 deletions(-) create mode 100755 lib/erl_docgen/priv/bin/xml_from_edoc.escript (limited to 'lib/erl_docgen') diff --git a/lib/erl_docgen/priv/bin/Makefile b/lib/erl_docgen/priv/bin/Makefile index bd59675003..95ad36216a 100644 --- 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 index 33a678d3a4..592b3985e4 100755 --- 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 \n"), + io:format("usage: codeline_preprocessing.escript \n"), halt(1). diff --git a/lib/erl_docgen/priv/bin/xml_from_edoc.escript b/lib/erl_docgen/priv/bin/xml_from_edoc.escript new file mode 100755 index 0000000000..ee79e82c3a --- /dev/null +++ b/lib/erl_docgen/priv/bin/xml_from_edoc.escript @@ -0,0 +1,149 @@ +#!/usr/bin/env escript +%% -*- erlang -*- +%% %CopyrightBegin% +%% +%% Copyright Ericsson AB 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 : xml_from_edoc.escript +%% +%% Created : 12 Dec 2009 by Lars Thorsen +%%---------------------------------------------------------------------- + + +%%====================================================================== +%% Records +%%====================================================================== +-record(args, {suffix=".xml", + layout=docb_edoc_xml_cb, + def=[], + includes=[], + preprocess=false, + sort_functions=true}). + + +%%====================================================================== +%% External functions +%%====================================================================== +%%---------------------------------------------------------------------- +%% Function: main/1 +%% Description: +%%---------------------------------------------------------------------- +main(RawOpts) -> + case catch parse(RawOpts, erlref, #args{}) of + {ok, File, Type, Args} -> + case Type of + erlref -> + module(File, Args); + chapter -> + users_guide(File, Args) + end; + {error, Msg} -> + io:format("~p\n", [Msg]), + usage() + end; +main(_) -> + usage(). + +%%====================================================================== +%% Internal functions +%%====================================================================== + +%%---------------------------------------------------------------------- +%% Function: usage/0 +%% Description: +%%---------------------------------------------------------------------- +usage() -> + io:format("usage: xml_from_edoc.escript [] \n"), + halt(1). + + +%%---------------------------------------------------------------------- +%% Function: module/2 +%% Description: +%%---------------------------------------------------------------------- +module(File, Args) -> + case filelib:is_regular(File) of + true -> + Opts = [{def, Args#args.def}, + {includes, Args#args.includes}, + {preprocess, Args#args.preprocess}, + {sort_functions, Args#args.sort_functions}, + + {app_default, "OTPROOT"}, + {file_suffix, Args#args.suffix}, + {dir, "."}, + {layout, Args#args.layout}], + edoc:file(File, Opts); + false -> + io:format("~s: not a regular file\n", [File]), + usage() + end. + + +%%---------------------------------------------------------------------- +%% Function: users_guide/2 +%% Description: +%%---------------------------------------------------------------------- +users_guide(File, Args) -> + case filelib:is_regular(File) of + true -> + Opts = [{def, Args#args.def}, + {app_default, "OTPROOT"}, + {file_suffix, Args#args.suffix}, + {layout, Args#args.layout}], + + Env = edoc_lib:get_doc_env(Opts), + + {ok, Tags} = + edoc_extract:file(File, overview, Env, Opts), + Data = + edoc_data:overview("Overview", Tags, Env, Opts), + F = fun(M) -> M:overview(Data, Opts) end, + Text = edoc_lib:run_layout(F, Opts), + + OutFile = "chapter" ++ Args#args.suffix, + edoc_lib:write_file(Text, ".", OutFile); + false -> + io:format("~s: not a regular file\n", [File]), + usage() + end. + + + +parse(["-xml" |RawOpts], Type, Args) -> + parse(RawOpts, Type, Args); % default, no update of record necessary +parse(["-sgml" |RawOpts], Type, Args) -> + parse(RawOpts, Type, Args#args{suffix=".sgml", layout=docb_edoc_sgml_cb}); +parse(["-chapter" |RawOpts], _Type, Args) -> + parse(RawOpts, chapter, Args); +parse(["-def", Key, Val |RawOpts], Type, Args) -> + Args2 = Args#args{def=Args#args.def++[{list_to_atom(Key), Val}]}, + parse(RawOpts, Type, Args2); + +parse(["-i", Dir |RawOpts], Type, Args) -> + Args2 = Args#args{includes=Args#args.includes++[Dir]}, + parse(RawOpts, Type, Args2); +parse(["-preprocess", Bool |RawOpts], Type, Args) when Bool == "true"; + Bool == "false" -> + parse(RawOpts, Type, Args#args{preprocess=list_to_atom(Bool)}); +parse(["-sort_functions", Bool |RawOpts], Type, Args) when Bool == "true"; + Bool == "false" -> + parse(RawOpts, Type, Args#args{sort_functions=list_to_atom(Bool)}); +parse([File], Type, Args) -> + {ok, File, Type, Args}; +parse([Opt | _RawOpts], _Type, _Args) -> + {error, io_lib:format("Bad option: ~p", [Opt])}. + diff --git a/lib/erl_docgen/priv/xsl/db_eix.xsl b/lib/erl_docgen/priv/xsl/db_eix.xsl index 929272256a..970b85ccb9 100644 --- a/lib/erl_docgen/priv/xsl/db_eix.xsl +++ b/lib/erl_docgen/priv/xsl/db_eix.xsl @@ -137,7 +137,20 @@ - + + + + + + + + + + + + + + @@ -178,26 +191,63 @@ - - - + + + + + + ( + ) + + + + + + + { + } + + + + + + [ + ] + + + + + + + + + + + + + + + + + - - - + + + - + - + + diff --git a/lib/erl_docgen/priv/xsl/db_html.xsl b/lib/erl_docgen/priv/xsl/db_html.xsl index 984655fc26..c2b58e48ec 100644 --- a/lib/erl_docgen/priv/xsl/db_html.xsl +++ b/lib/erl_docgen/priv/xsl/db_html.xsl @@ -2,20 +2,20 @@ @@ -40,6 +40,46 @@
+ @@ -543,7 +583,13 @@ false -
  • + + + loadscrollpos + no + + +
    • @@ -731,12 +777,19 @@ + + + loadscrollpos + no + + + -
    • +
      • @@ -788,58 +841,73 @@
      • - () - -
      • - - -
      • - - () - -
      • -
        - - - - - - - - - - - - - - - + () + + - - - +
      • + + () + +
      • -
        -
        - - - - - - - - - - -
      • - - / - -
      • -
        - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      • + + / + +
      • +
        + + @@ -1065,6 +1133,7 @@ +

        EXPORTS @@ -1121,11 +1190,26 @@
        -
        + + + + + + + + + + + + + + + + +
        - @@ -1167,6 +1251,7 @@ +

        @@ -1458,29 +1543,65 @@ + + + + + + ( + ) + + + + + + + { + } + + + + + + + [ + ] + + + + + + + + + + + + - - + + - - - + + + - + - + + diff --git a/lib/erl_docgen/priv/xsl/db_man.xsl b/lib/erl_docgen/priv/xsl/db_man.xsl index c759a77496..300d1ed362 100644 --- a/lib/erl_docgen/priv/xsl/db_man.xsl +++ b/lib/erl_docgen/priv/xsl/db_man.xsl @@ -2,20 +2,20 @@ @@ -37,14 +37,12 @@ - .RE .SH "" - - .RE + .SS "" @@ -53,9 +51,9 @@ - .RS 2 + .RS 2 - .RE + .RE @@ -65,72 +63,80 @@ - .br - .br + .LP - .RS 2 - - .RE + .RS 2 + + .RE - .TP 4 + .TP 2 .B - + : - - .br - .br + + + + + + .RS 2 + .LP .LP + + .RE + + - - - + + + + + + + + + + + - .TP 4 .B Note: + .SS Note: + - .TP 4 .B Warning: + .SS Warning: + - - - - - - .LP - - - - .LP + .LP - \fB + \fB - \fR\& + \fR\& @@ -138,19 +144,20 @@ - \fI\fR\& + \fI\fR\& - \fI\fR\& + \fI \fR\& - \fB\fR\& + \fB\fR\& + .LP .nf .fi @@ -158,6 +165,7 @@ + .LP .nf .fi @@ -168,16 +176,7 @@ - - - - + @@ -192,7 +191,7 @@ .TH 3 " " "Ericsson AB" "Erlang Module Definition" - .SH MODULE + .SH NAME \- @@ -225,7 +224,7 @@ .TH 6 " " "Ericsson AB" "Erlang Application Definition" .SH NAME - \- + \- @@ -297,9 +296,80 @@ - + + + + .SH AUTHORS + + + + + + .LP + + + + + + .I < + + > + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/lib/erl_docgen/priv/xsl/db_pdf.xsl b/lib/erl_docgen/priv/xsl/db_pdf.xsl index bef86277ea..e12b4d219a 100644 --- a/lib/erl_docgen/priv/xsl/db_pdf.xsl +++ b/lib/erl_docgen/priv/xsl/db_pdf.xsl @@ -2,20 +2,20 @@ @@ -229,7 +229,9 @@ - The contents of this file are subject to the Erlang Public License, + + + . @@ -382,7 +385,9 @@ - + + + @@ -422,8 +427,26 @@ + + + + + + + + + + + + + + + + + + - / + / @@ -668,12 +691,12 @@ - + - + Code listing . @@ -687,12 +710,12 @@ - + - + Code listing . @@ -862,7 +885,7 @@ - + Exports @@ -958,6 +981,7 @@ + @@ -1103,27 +1127,62 @@ + + + + + ( + ) + + + + + + + { + } + + + + + + + [ + ] + + + + + + + + + + + + - - + + - - - + + + - + - + + diff --git a/lib/erl_docgen/priv/xsl/db_pdf_params.xsl b/lib/erl_docgen/priv/xsl/db_pdf_params.xsl index e2e264b90a..7de20f2092 100644 --- a/lib/erl_docgen/priv/xsl/db_pdf_params.xsl +++ b/lib/erl_docgen/priv/xsl/db_pdf_params.xsl @@ -2,20 +2,20 @@ @@ -110,7 +110,7 @@ 0.9em - bold + @@ -248,6 +248,8 @@ 1em 1em 2em + 0.5em + 0.5em false preserve no-wrap @@ -266,8 +268,10 @@ justify 1em 0.3em - 1em - 1em + 0.5em + 0.5em + 0.5em + 0.5em always @@ -278,8 +282,10 @@ justify 1em 0.3em - 1em - 1em + 0.5em + 0.5em + 0.5em + 0.5em always -- cgit v1.2.3