Antwort: [Newsletter] Re: Log4net website issue

[Jo...@rohde-schwarz.com]

Dominik Psenner <dp...@gmail.com> wrote on 19.04.2017 10:40:17:
> 
> I completely purged that mess from my memory. We need a solution that 
> just works and links to generated code are not "the solution"©. :-) When 

> I build log4net I get the following files:
> 
> * log4net.dll
> * log4net.pdb
> * log4net.xml
> 
> The latter is a parseable output of all the classes, methods, 
> properties, .. along with the fancy source documentation (authors, 
> remarks, ..). Is it possible to do a little XPATH and XSLT kung-fu to 
> get this (and/or pieces from it) into a "site.xml"-ish format that could 

> later be consumed by the maven site plugin?

This sounds like the job for a (new?) Presentation Style for the 
Sandcastle Helpfile Builder [1]. I assume that staring from scratch will 
be a lot harder...
As an alternative, there is already a Markdown help file format available 
[2], maybe this can serve as the input for some pandoc pipe line.

The non-API parts of the documentation can also be handled by SHFB, using 
"Conceptual Documentation" [3] with verified links into/from the API/SDK 
parts.

[1]: https://github.com/EWSoftware/SHFB
[2]: 
http://ewsoftware.github.io/SHFB/html/6f0a80ec-b8ef-45d6-a55a-1fb7a6545ddc.htm
[3]: 
http://ewsoftware.github.io/MAMLGuide/html/303c996a-2911-4c08-b492-6496c82b3edb.htm

Regarding the consistency with other log4<X> projects, I as a .NET 
developer and log4net user, consider consistency with other .NET 
documentation (aka MSDN-Style) much more important then with let's say 
log4j.


Regards,
Jonas

> 
> On 2017-04-19 10:07, Stefan Bodewig wrote:
> > On 2017-04-18, Dominik Psenner wrote:
> >
> >> We probably should at least add a remark that points readers to the
> >> SDK reference and avoid the double effort of maintaining the
> >> documentation on the website too.
> > Likely, in particular since we've broken it twice during the 2.0.x
> > release series. Looks as if updating SHFB was bound to modify the file
> > names making deep links dangerous.
> >
> > You had fixed the link inside config-examples back in October and 
later
> > releases have broken them again - this was easy to fix using
> > mod_rewrite.
> >
> > I think I've found all other places and fixed them for the 2.0.8 site 
as
> > a short term fix.
> >
> > Stefan

Re: Antwort: [Newsletter] Re: Log4net website issue

[Dominik Psenner <dp...@gmail.com>]

> Regarding the consistency with other log4<X> projects, I as a .NET
> developer and log4net user, consider consistency with other .NET
> documentation (aka MSDN-Style) much more important then with let's say
> log4j.

I don't think either that we should re-style the SDK reference. The 
issue we try to solve here is that we currently have to place deep links 
into the generated MSDN-Style SDK reference sites and we regularly break 
those links from one release to the next. Options we have so far are:

  1) link to the SDK reference index page
  2) write parts of the documentation in the site
  3) generate parts of the website from the source code documentation

While (1) is trivial, users have to read the SDK reference to know all 
the available configuration options. It is fine by me, but the starter 
of this topic was unable to do so and therefore we should try to make 
this better. (2) is trivial too, but we have to synchronize the SDK 
documentation with the website which means more effort over the years. 
(3) is not trivial, sophisticated and much more initial work, but gives 
the same result as (2) without the need to duplicate the effort of 
maintenance.

We already have the MAML and we try to find a way to "Create the 
conceptual content" as mentioned at [1]. For now this is an completely 
abstract task to me but [2] should give more insights. Hints, ideas, 
help and patches welcome! :-)

Cheers,
Dominik

[1] http://ewsoftware.github.io/MAMLGuide/html/303c996a-2911-4c08-b492-6496c82b3edb.htm
[2] http://ewsoftware.github.io/MAMLGuide/html/86752a38-eba3-4174-bcbf-79ec8428ecf9.htm