Use of sections within a module group in doxygen - doxygen

Question

I seek the preferred way to structure the contents of a doxygen module group. For example I want to structure the #details text in the following module group in different sections. Especially each of the sections should appear in the bookmarks of the generated PDF (as child elements of the module group):
#defgroup lorem
#{
#brief
Lorem ipsum
#details
Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Ut purus elit, vestibulum
ut, placerat ac, adipiscing vitae, felis. Curabitur dictum gravida mauris. Nam arcu
libero, nonummy eget, consectetuer id, vulputate a, magna. Donec vehicula augue eu
neque.
Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis
egestas. Mauris ut leo. Cras viverra metus rhoncus sem. Nulla et lectus vestibulum
urna fringilla ultrices. Phasellus eu tellus sit amet tortor gravida placerat.
Integer sapien est, iaculis in, pretium quis, viverra ac, nunc.
Praesent eget sem vel leo ultrices bibendum. Aenean faucibus. Morbi dolor nulla,
malesuada eu, pulvinar at, mollis ac, nulla. Curabitur auctor semper nulla.
Donec varius orci eget risus. Duis nibh mi, congue eu, accumsan eleifend,
sagittis quis, diam. Duis eget orci sit amet orci dignissim rutrum.
#}
A way could be using #section #subsection etc, but the doxygen manual says:
Warning:
This command only works inside related page documentation
and not in other documentation blocks!
Is it possible to use #section or are there other (better) ways to do this?
Edit:
The behavior using #section seems indeed odd, for example I tried something like this:
#defgroup lorem
#{
#brief
Lorem ipsum
#section sec0 Lorem ipsum
Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Ut purus elit, vestibulum
ut, placerat ac, adipiscing vitae, felis. Curabitur dictum gravida mauris. Nam arcu
libero, nonummy eget, consectetuer id, vulputate a, magna. Donec vehicula augue eu
neque.
#section sec1 Pellentesque
Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis
egestas. Mauris ut leo. Cras viverra metus rhoncus sem. Nulla et lectus vestibulum
urna fringilla ultrices. Phasellus eu tellus sit amet tortor gravida placerat.
#section sec2 Integer sapien est
Integer sapien est, iaculis in, pretium quis, viverra ac, nunc.
Praesent eget sem vel leo ultrices bibendum. Aenean faucibus. Morbi dolor nulla,
malesuada eu, pulvinar at, mollis ac, nulla. Curabitur auctor semper nulla.
Donec varius orci eget risus.
Duis nibh mi, congue eu, accumsan eleifend,
sagittis quis, diam. Duis eget orci sit amet orci dignissim rutrum.
#}
The result looks fine and has in this case the following structure in the PDF:
4.1 lorem
4.1.1 Lorem ipsum
4.1.2 Pellentesque
4.1.3 Integer sapien est
Now if a add #file a #details section containing no text appears in the output I can't get rid of. It looks like this (I also tested adding another group containing a #file - same result):
4.1 lorem
4.1.1 Detailed Description
4.1.2 Lorem ipsum
4.1.3 Pellentesque
4.1.4 Integer sapien est
Then I tried to move the sections and make them subsections of the "Detailed Description" -which would be logically okay. But when I change them to #subsection 's they completely disappear. Doxygen warns in this case it has found a subsection out of section context so obviously it doesn't realize it generated this mysterious empty #details section.
Next idea was to use the Markdown support to do it. In this case sections aren't put into the PDF bookmarks so it looks okay - but in latex code they are still on same level as the #details section. And subsections in Markdown disappear as well. I've no idea what is going on, but I can't be the first person trying to structure things in a module group.

Answer 1

I tried your example myself and if you put the #file between your #{ ... #} like this,
/**
#defgroup lorem
#{
...
#file
#}
*/
then the standard Doxygen Layout is created.
If you move the #file outside, then your like this, then it should work.
/**
#defgroup lorem
#{
...
#}
#file
*/
However, if you really need the #file within your #defgroup lorem #{ ... #}, there are two ways to achive it.
FIRST:
/**
#defgroup file
#{
#file
#defgroup lorem
#{
...
#}
#}
*/
SECOND:
Change the standard doxygen layout.
To do this, follow the manuals description here, beginning at: Changing the layout of pages, by creating your custom DoxygenLayout.xml.
Now, edit the DoxygenLayout.xml and search for the <group> tag.
There will find <detaileddescription title=""/> tag, change it to <detaileddescription visible="no" title=""/>and the `Detailed Description" bugging you should vanish.

Answer 2

If you simply want to structure the sections within a group description then I'd simply use HTML and insert <h1>Section name here<\h1> etc.
Alternatively Markdown ## section marking may work.
I don't know how well these percolate to LaTex and PDF as I've never used that output route. However, I'm confident that using HTML will give more reliable results than using #section which, as the manual warns, is simply not designed for use here, but, instead, as part of the #page / #section / #subsection hierarchy for bulk prose. These command sets do not mix well in Doxygen.
Locating #file in exotic positions (as per aldr's suggestion) is prone to cause very strange results. It's simply the description block for the physical file, and is best used as just that.