edoc custom XML layout

[Richard Carlsson]

Serge Aleynikov wrote:
> As the edoc's documentation doesn't mention the guidelines for creating
> custom layouts, is there any reference or samples with some helpful info
> (other than the *.erl sources)?

Sorry, but no. And actually, the edoc_layout.erl module is really an ad hoc
piece of junk that I'd like to rewrite completely. But it's pretty simple
to follow what it does, if you want to write your own layout module.

Believe me, if I had had any guidelines when I wrote that thing, I would
have been happier, because then I could have followed them myself.
I guess I was hoping for some trigger happy young'un with a degree
in web design to turn up and rewrite it for me. At least now I know
how not to do it, which is a start.

> I tried to call edoc:read/2, but it doesn't seem to work with
> otpsgml_layout:
> 25> edoc:read("edoc_layout.erl", [{layout, otpsgml_layout}]).
> edoc: error in layout 'otpsgml_layout':
> {'EXIT',{badarg,[{erlang,binary_to_list,[{aname,[[82,105,99,104,97,114,100|...]]}]},{xmerl_lib,export_text,2},{xmerl_lib,export_text,2},{xmerl,apply_cb,5},{xmerl,export_content,2},{xmerl,export_content,2},{xmerl,export_content,2},{xmerl,export_content,2}]}}.
> 
> ** exited: error **

There's a bug in the otpsgml_layout module which makes it generate
malformed data for 'author' declarations. Here's a patch if you like
(it's been checked in and will show up in the next release):

--- src/otpsgml_layout.erl      10 Dec 2005 17:51:33 -0000      1.12
+++ src/otpsgml_layout.erl      5 Jul 2006 20:56:07 -0000
@@ -165,7 +165,7 @@
     {Short,Long} = find_first_p(FullDesc,[]),
     Description = {description, [?NL,{p,Short}|Long]++[?NL|types(SortedTs)]},
     Funcs = functions(SortedFs),
-    Authors = authors(Es),
+    Authors = {authors, authors(Es)},
     See = sees1(Es),
     {erlref, [
              ?NL,Header,

> Is my assumption correct that I would need to create a xxx_layout.erl
> module similar to otpsgml_layout, and then make the following call to
> generate edoc documentation using that layout:
> 
> edoc:run([], ["my_file.erl"], [{layout, xxx_layout}]).

Yes, or via any of the other main functions (application/2, files/2,
packages/2), or as you did in your example via read/2.

> I am only guessing because edoc:run/3 doesn't mention the {layout,
> Layout} option.

But it does however say "Also see layout/2 for layout-related options",
and layout/2 describes the {layout, Module} option.

Anyway, good luck!

	/Richard

-- 
 "Having users is like optimization: the wise course is to delay it."
   -- Paul Graham