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/stdlib/doc/src/beam_lib.xml | 152 ++++++++++++++++++----------------- lib/stdlib/doc/src/io.xml | 9 ++- lib/stdlib/doc/src/unicode.xml | 4 +- lib/stdlib/doc/src/unicode_usage.xml | 6 +- 4 files changed, 91 insertions(+), 80 deletions(-) (limited to 'lib/stdlib') diff --git a/lib/stdlib/doc/src/beam_lib.xml b/lib/stdlib/doc/src/beam_lib.xml index f2a9c2a671..b9286f1402 100644 --- a/lib/stdlib/doc/src/beam_lib.xml +++ b/lib/stdlib/doc/src/beam_lib.xml @@ -4,7 +4,7 @@
- 20002009 + 20002010 Ericsson AB. All Rights Reserved. @@ -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. - + beam_lib @@ -70,82 +70,88 @@ using strip/1, strip_files/1 and/or strip_release/1.

-

Reconstructing source code

-

Here is an example of how to reconstruct source code from - the debug information in a BEAM file Beam:

- +
+ Reconstructing source code +

Here is an example of how to reconstruct source code from + the debug information in a BEAM file Beam:

+ {ok,{_,[{abstract_code,{_,AC}}]}} = beam_lib:chunks(Beam,[abstract_code]). io:fwrite("~s~n", [erl_prettypr:format(erl_syntax:form_list(AC))]). -

Encrypted debug information

-

The debug information can be encrypted in order to keep - the source code secret, but still being able to use tools such as - Xref or Debugger.

-

To use encrypted debug information, a key must be provided to - the compiler and beam_lib. The key is given as a string and - it is recommended that it contains at least 32 characters and - that both upper and lower case letters as well as digits and - special characters are used.

-

-

The default type -- and currently the only type -- of crypto - algorithm is des3_cbc, three rounds of DES. The key string - will be scrambled using erlang:md5/1 to generate - the actual keys used for des3_cbc.

- -

As far as we know by the time of writing, it is - infeasible to break des3_cbc encryption without any - knowledge of the key. Therefore, as long as the key is kept - safe and is unguessable, the encrypted debug information - should be safe from intruders.

- -

There are two ways to provide the key:

- - -

Use the compiler option {debug_info,Key}, see - compile(3), - and the function - crypto_key_fun/1 - to register a fun which returns the key whenever - beam_lib needs to decrypt the debug information.

-

If no such fun is registered, beam_lib will instead - search for a .erlang.crypt file, see below.

- - -

Store the key in a text file named .erlang.crypt.

-

In this case, the compiler option encrypt_debug_info - can be used, see - compile(3).

- - -

.erlang.crypt

-

beam_lib searches for .erlang.crypt in the current - directory and then the home directory for the current user. If - the file is found and contains a key, beam_lib will - implicitly create a crypto key fun and register it.

-

The .erlang.crypt file should contain a single list of - tuples:

- +
+
+ Encrypted debug information +

The debug information can be encrypted in order to keep + the source code secret, but still being able to use tools such as + Xref or Debugger.

+

To use encrypted debug information, a key must be provided to + the compiler and beam_lib. The key is given as a string and + it is recommended that it contains at least 32 characters and + that both upper and lower case letters as well as digits and + special characters are used.

+

+

The default type -- and currently the only type -- of crypto + algorithm is des3_cbc, three rounds of DES. The key string + will be scrambled using erlang:md5/1 to generate + the actual keys used for des3_cbc.

+ +

As far as we know by the time of writing, it is + infeasible to break des3_cbc encryption without any + knowledge of the key. Therefore, as long as the key is kept + safe and is unguessable, the encrypted debug information + should be safe from intruders.

+ +

There are two ways to provide the key:

+ + +

Use the compiler option {debug_info,Key}, see + compile(3), + and the function + crypto_key_fun/1 + to register a fun which returns the key whenever + beam_lib needs to decrypt the debug information.

+

If no such fun is registered, beam_lib will instead + search for a .erlang.crypt file, see below.

+ + +

Store the key in a text file named .erlang.crypt.

+

In this case, the compiler option encrypt_debug_info + can be used, see + compile(3).

+ + +
+
+ .erlang.crypt +

beam_lib searches for .erlang.crypt in the current + directory and then the home directory for the current user. If + the file is found and contains a key, beam_lib will + implicitly create a crypto key fun and register it.

+

The .erlang.crypt file should contain a single list of + tuples:

+ {debug_info, Mode, Module, Key} -

Mode is the type of crypto algorithm; currently, the only - allowed value thus is des3_cbc. Module is either an - atom, in which case Key will only be used for the module - Module, or [], in which case Key will be - used for all modules. Key is the non-empty key string.

-

The Key in the first tuple where both Mode and - Module matches will be used.

-

Here is an example of an .erlang.crypt file that returns - the same key for all modules:

- Mode is the type of crypto algorithm; currently, the only + allowed value thus is des3_cbc. Module is either an + atom, in which case Key will only be used for the module + Module, or [], in which case Key will be + used for all modules. Key is the non-empty key string.

+

The Key in the first tuple where both Mode and + Module matches will be used.

+

Here is an example of an .erlang.crypt file that returns + the same key for all modules:

+ 7}|pc/DM6Cga*68$Mw]L#&_Gejr]G^"}].]]> -

And here is a slightly more complicated example of an - .erlang.crypt which provides one key for the module - t, and another key for all other modules:

- And here is a slightly more complicated example of an + .erlang.crypt which provides one key for the module + t, and another key for all other modules:

+ 7}|pc/DM6Cga*68$Mw]L#&_Gejr]G^"}].]]> - -

Do not use any of the keys in these examples. Use your own - keys.

- + +

Do not use any of the keys in these examples. Use your own + keys.

+ +
diff --git a/lib/stdlib/doc/src/io.xml b/lib/stdlib/doc/src/io.xml index c075f11792..6f9d979c9a 100644 --- a/lib/stdlib/doc/src/io.xml +++ b/lib/stdlib/doc/src/io.xml @@ -4,7 +4,7 @@
- 19962009 + 19962010 Ericsson AB. All Rights Reserved. @@ -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. - + io @@ -1003,7 +1003,8 @@ enter>bar. Standard Error

In certain situations, especially when the standard output is redirected, access to an io_server() specific for error messages might be convenient. The io_device 'standard_error' can be used to direct output to whatever the current operating system considers a suitable device for error output. Example on a Unix-like operating system:

-$ erl -noshell -noinput -eval 'io:format(standard_error,"Error: ~s~n",["error 11"]),init:stop().' > /dev/null
+$ erl -noshell -noinput -eval 'io:format(standard_error,"Error: ~s~n",["error 11"]),'\
+'init:stop().' > /dev/null
 Error: error 11
diff --git a/lib/stdlib/doc/src/unicode.xml b/lib/stdlib/doc/src/unicode.xml index b3aad51591..60edd8ade9 100644 --- a/lib/stdlib/doc/src/unicode.xml +++ b/lib/stdlib/doc/src/unicode.xml @@ -51,7 +51,9 @@ charlist() = [unicode_char() | unicode_binary() | charlist()] a unicode_binary is allowed as the tail of the list -external_unicode_binary() = binary() with characters coded in a user specified Unicode encoding other than UTF-8 (UTF-16 or UTF-32) +external_unicode_binary() = binary() + with characters coded in a user specified Unicode encoding other + than UTF-8 (UTF-16 or UTF-32) external_chardata() = external_charlist() | external_unicode_binary() diff --git a/lib/stdlib/doc/src/unicode_usage.xml b/lib/stdlib/doc/src/unicode_usage.xml index 06347b3aae..c5bf10b63d 100644 --- a/lib/stdlib/doc/src/unicode_usage.xml +++ b/lib/stdlib/doc/src/unicode_usage.xml @@ -76,7 +76,8 @@ charlist() = [unicode_char() | unicode_binary() | charlist()] a unicode_binary is allowed as the tail of the list

The module unicode in stdlib even supports similar mixes with binaries containing other encodings than UTF-8, but that is a special case to allow for conversions to and from external data:

-external_unicode_binary() = binary() with characters coded in a user specified Unicode encoding other than UTF-8 (UTF-16 or UTF-32) +external_unicode_binary() = binary() with characters coded in a user specified Unicode + encoding other than UTF-8 (UTF-16 or UTF-32) external_chardata() = external_charlist() | external_unicode_binary() @@ -93,7 +94,8 @@ external_charlist() = [unicode_char() | external_unicode_binary() | external_cha <<Ch/utf8,_/binary>> = Bin1, <<Ch/utf16-little,_/binary>> = Bin2, -Bin3 = <<$H/utf32-little, $e/utf32-little, $l/utf32-little, $l/utf32-little, $o/utf32-little>>, +Bin3 = <<$H/utf32-little, $e/utf32-little, $l/utf32-little, $l/utf32-little, + $o/utf32-little>>,

For convenience, literal strings can be encoded with a Unicode encoding in binaries using the following (or similar) syntax:

Bin4 = <<"Hello"/utf16>>, -- cgit v1.2.3