New reader for a subset of Doxygen markup

New reader for a subset of Doxygen markup

[Alex Reicher]

[-- Attachment #1.1: Type: text/plain, Size: 1714 bytes --]

Dear Mr. MacFarlane,

At work I maintain an API in pure C (not C++) and use Doxygen markup for 
in-line documentation. I use Doxygen LaTeX output to generate a PDF that 
customers receive as reference manual, but the result leaves much to be 
desired. The auto-generated reference manual is cluttered and poorly 
organized. This is true of other Doxygen output formats (HTML, DocBook, 
native Doxygen XML). They all represent the same document structure, that I 
dislike.

I've been thinking to add a pandoc reader that does exactly what I need, 
namely parsing a subset of Doxygen markup that we use and convert it to a 
Pandoc that represents a well-organized, C-oriented reference manual. Then 
I can use pandoc's PDF output option.

What would be your reaction? One of:

1. "pandoc is open-source, so please fork it as you like, as long you abide 
by the GPL. But what you describe is of a too narrow interest, so I won't 
merge it into mainline."
2. "That's the wrong way to approach your problem. You should <insert sage 
advice>."
3. "That sounds interesting. If I like your patch, I will merge it into 
mainline."
4. <other>

Thanks!

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/14de3f5d-cca6-46ce-8291-7d92859a4c14%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[-- Attachment #1.2: Type: text/html, Size: 2347 bytes --]

Re: New reader for a subset of Doxygen markup

[Mark Szepieniec]

[-- Attachment #1: Type: text/plain, Size: 3070 bytes --]

Hello Alex,

I'm not Mr. MacFarlane, but I don't quite understand the problem you're
having, so it might help if you explain it in more detail, or give an
example. Are you wnating to reorganize sections, leave certain sections
out, or something else? Also, perhaps include why this might be useful
enough to others to be considered for mergeing.

Note that altering document structure can be done quite easily with a
pandoc filter.

Hope this helps,
mark

On Thu, Aug 27, 2015 at 10:59 PM, Alex Reicher <alex.reicher-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
wrote:

> Dear Mr. MacFarlane,
>
> At work I maintain an API in pure C (not C++) and use Doxygen markup for
> in-line documentation. I use Doxygen LaTeX output to generate a PDF that
> customers receive as reference manual, but the result leaves much to be
> desired. The auto-generated reference manual is cluttered and poorly
> organized. This is true of other Doxygen output formats (HTML, DocBook,
> native Doxygen XML). They all represent the same document structure, that I
> dislike.
>
> I've been thinking to add a pandoc reader that does exactly what I need,
> namely parsing a subset of Doxygen markup that we use and convert it to a
> Pandoc that represents a well-organized, C-oriented reference manual. Then
> I can use pandoc's PDF output option.
>
> What would be your reaction? One of:
>
> 1. "pandoc is open-source, so please fork it as you like, as long you
> abide by the GPL. But what you describe is of a too narrow interest, so I
> won't merge it into mainline."
> 2. "That's the wrong way to approach your problem. You should <insert sage
> advice>."
> 3. "That sounds interesting. If I like your patch, I will merge it into
> mainline."
> 4. <other>
>
> Thanks!
>
> --
> You received this message because you are subscribed to the Google Groups
> "pandoc-discuss" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
> To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/pandoc-discuss/14de3f5d-cca6-46ce-8291-7d92859a4c14%40googlegroups.com
> <https://groups.google.com/d/msgid/pandoc-discuss/14de3f5d-cca6-46ce-8291-7d92859a4c14%40googlegroups.com?utm_medium=email&utm_source=footer>
> .
> For more options, visit https://groups.google.com/d/optout.
>

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/CAE4-1rUBL1wO%3DDvAkgh-wOPNwfBB5OUUU6V_VXOTMB4rfJxK4g%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

[-- Attachment #2: Type: text/html, Size: 4496 bytes --]

Re: New reader for a subset of Doxygen markup

[John MACFARLANE]

I don't know much about Doxygen.  But, from what I know now,
this sounds like a nice idea.  I'd certainly consider merging it.
But it might make more sense to develop it as a separate
tool, using the pandoc library.  I'm not sure which option
is better, but most of the work would be the same in either
case and you could easily switch from one to the other.

++ Alex Reicher [Aug 27 15 14:59 ]:
>   Dear Mr. MacFarlane,
>   At work I maintain an API in pure C (not C++) and use Doxygen markup
>   for in-line documentation. I use Doxygen LaTeX output to generate a PDF
>   that customers receive as reference manual, but the result leaves much
>   to be desired. The auto-generated reference manual is cluttered and
>   poorly organized. This is true of other Doxygen output formats (HTML,
>   DocBook, native Doxygen XML). They all represent the same document
>   structure, that I dislike.
>   I've been thinking to add a pandoc reader that does exactly what I
>   need, namely parsing a subset of Doxygen markup that we use and convert
>   it to a Pandoc that represents a well-organized, C-oriented reference
>   manual. Then I can use pandoc's PDF output option.
>   What would be your reaction? One of:
>   1. "pandoc is open-source, so please fork it as you like, as long you
>   abide by the GPL. But what you describe is of a too narrow interest, so
>   I won't merge it into mainline."
>   2. "That's the wrong way to approach your problem. You should <insert
>   sage advice>."
>   3. "That sounds interesting. If I like your patch, I will merge it into
>   mainline."
>   4. <other>
>   Thanks!
>
>   --
>   You received this message because you are subscribed to the Google
>   Groups "pandoc-discuss" group.
>   To unsubscribe from this group and stop receiving emails from it, send
>   an email to [1]pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
>   To post to this group, send email to
>   [2]pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
>   To view this discussion on the web visit
>   [3]https://groups.google.com/d/msgid/pandoc-discuss/14de3f5d-cca6-46ce-
>   8291-7d92859a4c14%40googlegroups.com.
>   For more options, visit [4]https://groups.google.com/d/optout.
>
>References
>
>   1. mailto:pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
>   2. mailto:pandoc-discuss-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
>   3. https://groups.google.com/d/msgid/pandoc-discuss/14de3f5d-cca6-46ce-8291-7d92859a4c14-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org?utm_medium=email&utm_source=footer
>   4. https://groups.google.com/d/optout