New tutorial for NLog - help needed

[Jaroslaw_Kowalski]

Hi!

I've written a new tutorial for NLog that describes the most current
version - 20060528 snapshot. It tells the story from Visual Studio user's
perspective: intellisense, snippets and so on. The tutorial will replace the
one currently on the website when the new version (probably 0.97) is
released.

Read it here:

http://www.nlog-project.org/snapshots/20060528/web/tutorial.html

The article is feature-complete, but it's still in write-only mode and
definitely requires proofreading and grammar fixes. I would be very grateful
if someone, whose primary language is English, would read the article and
suggest the required wording changes.

The source file for the tutorial is here:

http://svn.nlog-project.org/repos/nlog/trunk/NLog/web/tutorial.xml

I'd really welcome the updated version of this file or just a list of change
suggestions sent here.

One note - the "tutorial" version of this article will have a different
introduction. This one is for the magazine     article.

Jarek



-------------------------------------------------------
All the advantages of Linux Managed Hosting--Without the Cost and Risk!
Fully trained technicians. The highest number of Red Hat certifications in
the hosting industry. Fanatical Support. Click to learn more
http://sel.as-us.falkag.net/sel?cmd=lnk&kid=107521&bid=248729&dat=121642
_______________________________________________
Nlog-list mailing list
Nlog-list@...
https://lists.sourceforge.net/lists/listinfo/nlog-list

[Ron Grabowski]

I made it down to the Rules section. I'll finish up later.

Website:
"Few years later, the world..."
Ron:
That doens't sound right. It shoud be something like "Today's world has
seen huge..."

Website:
"Every one of us has surely written code similar to the following:"
Ron:
"We've all written code similiar to the following:"

Website:
"Console.WriteLine() statements in the above example are called
"tracing statements", because"
Ron:
"Console.WriteLine() statements in the above example are called
"tracing statements" because"

Website:
"the ability to control"...
Ron:
The first two bullet points end with a period but don't start with a
capital letter.

Website:
"Notice how Visual Studio suggests us the possible..."
Ron:
"Notice how Visual Studio suggests to us the possible..."
"Notice how Visual Studio suggests the possible..."

Website:
"It's probably the best idea to use logger names which..."
Ron:
"It's recommended that logger names correspond to the full class names
in the application. The LogManager object has a
GetCurrentClassLogger() method that automatically creates a logger
based on the class its being called from."

Website:
"Let's assume, that we also want our log messages to go to a file..."
Ron:
"Let's record our log messages, along with some contextual information
such as the the current stack trace, to both a file and the console. To
do this we need to defined another <target /> of type "File" and tell
the <logger /> node that we want write to it."

Website:
"When we run the program, the following information will be written to
the "file.txt" in the application directory:"
Ron:
Where is the => coming from? I didn't see it in the file target's
layout. Does the ${stacktrace} automatically insert a =>?

Website:
"different level of detal depending"
Ron:
"different level of detail depending"

Website:
"After running the program we find that Trace and Debug messages can
only be found in the file, while they aren't displayed to the console."
Ron:
"After running the program we find that Trace and Debug messages are
only found in the file and aren't displayed on the console."

Website:
"The following files are being attempted for a stand-alone *.exe
application:"
Ron:
"The following locations will be searched when executing a stand-alone
*.exe application:"

Website:
".NET Compact Framework doesn't have the notion of an..."
Ron:
"The .NET Compact Framework doesn't recognize application configuration
files..."

Website:
"and can be used in advanced scenarios."
Ron:
"and can be useful in advanced scenarios."

General comments:

You may want to highlight the fact that things like "#if DEBUG" are
messy.

Make a quick comment explaining that Loggers are relatively expensive
to create and that there its common to have a single static logger
per class. Having a static per-class logger is ok even in
multi-threaded environments like ASP.Net.

Try not to start a lot of sentances with a couple words then a comma.
I'm guilty of doing this too. The current annoying thing that I notice
about myself is that I start a lot of sentances with "I think" :-)

--- Jaroslaw Kowalski <jaak@...> wrote:

> Hi!
>
> I've written a new tutorial for NLog that describes the most current
> version - 20060528 snapshot. It tells the story from Visual Studio
> user's
> perspective: intellisense, snippets and so on. The tutorial will
> replace the
> one currently on the website when the new version (probably 0.97) is
> released.
>
> Read it here:
>
> http://www.nlog-project.org/snapshots/20060528/web/tutorial.html
>
> The article is feature-complete, but it's still in write-only mode
> and
> definitely requires proofreading and grammar fixes. I would be very
> grateful
> if someone, whose primary language is English, would read the article
> and
> suggest the required wording changes.
>
> The source file for the tutorial is here:
>
> http://svn.nlog-project.org/repos/nlog/trunk/NLog/web/tutorial.xml
>
> I'd really welcome the updated version of this file or just a list of
> change
> suggestions sent here.
>
> One note - the "tutorial" version of this article will have a
> different
> introduction. This one is for the magazine     article.
>
> Jarek
>
>
>
> -------------------------------------------------------
> All the advantages of Linux Managed Hosting--Without the Cost and
> Risk!
> Fully trained technicians. The highest number of Red Hat
> certifications in
> the hosting industry. Fanatical Support. Click to learn more
>

http://sel.as-us.falkag.net/sel?cmd=lnk&kid=107521&bid=248729&dat=121642
> _______________________________________________
> Nlog-list mailing list
> Nlog-list@...
> https://lists.sourceforge.net/lists/listinfo/nlog-list
>



-------------------------------------------------------
All the advantages of Linux Managed Hosting--Without the Cost and Risk!
Fully trained technicians. The highest number of Red Hat certifications in
the hosting industry. Fanatical Support. Click to learn more
http://sel.as-us.falkag.net/sel?cmd=lnk&kid=107521&bid=248729&dat=121642
_______________________________________________
Nlog-list mailing list
Nlog-list@...
https://lists.sourceforge.net/lists/listinfo/nlog-list

[Jaroslaw_Kowalski]

Thanks Ron.

I've modified the tutorial by replacing the old version at the same url,
because many websites are linking directly to the snapshot:

http://www.nlog-project.org/snapshots/20060528/web/tutorial.html

Regarding your question:

> Where is the => coming from? I didn't see it in the file target's
> layout. Does the ${stacktrace} automatically insert a =>?

Yes, I've just added the "separator" option that can be used to modify it.

${stacktrace:separator=,:format=DetailedFlat}

It's available in the latest snapshot, which I'll be uploading in a moment:

http://www.nlog-project.org/snapshots/20060531/

Jarek
----- Original Message -----
From: "Ron Grabowski" <rongrabowski@...>
To: <nlog-list@...>
Sent: Wednesday, May 31, 2006 7:17 AM
Subject: Re: [Nlog-list] New tutorial for NLog - help needed

>I made it down to the Rules section. I'll finish up later.
>
> Website:
> "Few years later, the world..."
> Ron:
> That doens't sound right. It shoud be something like "Today's world has
> seen huge..."
>
> Website:
> "Every one of us has surely written code similar to the following:"
> Ron:
> "We've all written code similiar to the following:"
>
> Website:
> "Console.WriteLine() statements in the above example are called
> "tracing statements", because"
> Ron:
> "Console.WriteLine() statements in the above example are called
> "tracing statements" because"
>
> Website:
> "the ability to control"...
> Ron:
> The first two bullet points end with a period but don't start with a
> capital letter.
>
> Website:
> "Notice how Visual Studio suggests us the possible..."
> Ron:
> "Notice how Visual Studio suggests to us the possible..."
> "Notice how Visual Studio suggests the possible..."
>
> Website:
> "It's probably the best idea to use logger names which..."
> Ron:
> "It's recommended that logger names correspond to the full class names
> in the application. The LogManager object has a
> GetCurrentClassLogger() method that automatically creates a logger
> based on the class its being called from."
>
> Website:
> "Let's assume, that we also want our log messages to go to a file..."
> Ron:
> "Let's record our log messages, along with some contextual information
> such as the the current stack trace, to both a file and the console. To
> do this we need to defined another <target /> of type "File" and tell
> the <logger /> node that we want write to it."
>
> Website:
> "When we run the program, the following information will be written to
> the "file.txt" in the application directory:"
> Ron:
> Where is the => coming from? I didn't see it in the file target's
> layout. Does the ${stacktrace} automatically insert a =>?
>
> Website:
> "different level of detal depending"
> Ron:
> "different level of detail depending"
>
> Website:
> "After running the program we find that Trace and Debug messages can
> only be found in the file, while they aren't displayed to the console."
> Ron:
> "After running the program we find that Trace and Debug messages are
> only found in the file and aren't displayed on the console."
>
> Website:
> "The following files are being attempted for a stand-alone *.exe
> application:"
> Ron:
> "The following locations will be searched when executing a stand-alone
> *.exe application:"
>
> Website:
> ".NET Compact Framework doesn't have the notion of an..."
> Ron:
> "The .NET Compact Framework doesn't recognize application configuration
> files..."
>
> Website:
> "and can be used in advanced scenarios."
> Ron:
> "and can be useful in advanced scenarios."
>
> General comments:
>
> You may want to highlight the fact that things like "#if DEBUG" are
> messy.
>
> Make a quick comment explaining that Loggers are relatively expensive
> to create and that there its common to have a single static logger
> per class. Having a static per-class logger is ok even in
> multi-threaded environments like ASP.Net.
>
> Try not to start a lot of sentances with a couple words then a comma.
> I'm guilty of doing this too. The current annoying thing that I notice
> about myself is that I start a lot of sentances with "I think" :-)
>
> --- Jaroslaw Kowalski <jaak@...> wrote:
>
>> Hi!
>>
>> I've written a new tutorial for NLog that describes the most current
>> version - 20060528 snapshot. It tells the story from Visual Studio
>> user's
>> perspective: intellisense, snippets and so on. The tutorial will
>> replace the
>> one currently on the website when the new version (probably 0.97) is
>> released.
>>
>> Read it here:
>>
>> http://www.nlog-project.org/snapshots/20060528/web/tutorial.html
>>
>> The article is feature-complete, but it's still in write-only mode
>> and
>> definitely requires proofreading and grammar fixes. I would be very
>> grateful
>> if someone, whose primary language is English, would read the article
>> and
>> suggest the required wording changes.
>>
>> The source file for the tutorial is here:
>>
>> http://svn.nlog-project.org/repos/nlog/trunk/NLog/web/tutorial.xml
>>
>> I'd really welcome the updated version of this file or just a list of
>> change
>> suggestions sent here.
>>
>> One note - the "tutorial" version of this article will have a
>> different
>> introduction. This one is for the magazine     article.
>>
>> Jarek
>>
>>
>>
>> -------------------------------------------------------
>> All the advantages of Linux Managed Hosting--Without the Cost and
>> Risk!
>> Fully trained technicians. The highest number of Red Hat
>> certifications in
>> the hosting industry. Fanatical Support. Click to learn more
>>
> http://sel.as-us.falkag.net/sel?cmd=lnk&kid=107521&bid=248729&dat=121642
>> _______________________________________________
>> Nlog-list mailing list
>> Nlog-list@...
>> https://lists.sourceforge.net/lists/listinfo/nlog-list
>>
>
>
>
> -------------------------------------------------------
> All the advantages of Linux Managed Hosting--Without the Cost and Risk!
> Fully trained technicians. The highest number of Red Hat certifications in
> the hosting industry. Fanatical Support. Click to learn more
> http://sel.as-us.falkag.net/sel?cmd=lnk&kid=107521&bid=248729&dat=121642
> _______________________________________________
> Nlog-list mailing list
> Nlog-list@...
> https://lists.sourceforge.net/lists/listinfo/nlog-list
>

-------------------------------------------------------
All the advantages of Linux Managed Hosting--Without the Cost and Risk!
Fully trained technicians. The highest number of Red Hat certifications in
the hosting industry. Fanatical Support. Click to learn more
http://sel.as-us.falkag.net/sel?cmd=lnk&kid=107521&bid=248729&dat=121642
_______________________________________________
Nlog-list mailing list
Nlog-list@...
https://lists.sourceforge.net/lists/listinfo/nlog-list

[Glenn E. Lanier, II]

> From: Ron Grabowski
> Sent: Wednesday, May 31, 2006 12:18 AM

> Website:
> "It's probably the best idea to use logger names which..."
> Ron:
> "It's recommended that logger names correspond to the full class names
> in the application. The LogManager object has a
> GetCurrentClassLogger() method that automatically creates a logger
> based on the class its being called from."

based on the class it's called from."

Or (preferably)

Based on the class from which it is called."

--G



-------------------------------------------------------
All the advantages of Linux Managed Hosting--Without the Cost and Risk!
Fully trained technicians. The highest number of Red Hat certifications in
the hosting industry. Fanatical Support. Click to learn more
http://sel.as-us.falkag.net/sel?cmd=lnk&kid=107521&bid=248729&dat=121642
_______________________________________________
Nlog-list mailing list
Nlog-list@...
https://lists.sourceforge.net/lists/listinfo/nlog-list

[Ron Grabowski]

website:
"Each rule can also be final..."
Ron:
"Rules are processed starting with the first rule in the list. When a
rule matches, log messages are directed to target(s) in that rule. If a
rule is marked as final, rules beneath the current rule are not
processed."

Website:
"NLog provides include file mechanism for that..."
Ron:
"NLog provides an include file mechanism for that..."

Website:
"It's worth to notice that filename may include..."
Ron:
"It's worth noting that filename may include..."
"It's worth noting that the file attribute, just like all attributes in
NLog config file(s), may include dynamic values using the familiar
${var} notation."

Website:
"Configuration file is read automatically read at program startup."
Ron:
"The configuration file is read automatically at program startup."

Website:
"...it's sometimes desired to temporarily increase..."
Ron:
"...it's sometimes desirable to temporarily increase..."

Website:
"To allow for such reconfiguration, NLog can ..."
Ron:
The sentance would still make sense if the beginning part "To allow for
such reconfiguration" were ommitted.

Website:
"Because NLog "eats" any exceptions that may occur during logging,
application may not be notified about any problems."
Ron:
"Because NLog "eats" any exceptions that may occur during logging, an
application may not be notified when problems occur."
Some textbooks recommend not starting a sentance with the word
'because'. Here's another possible way of explaining things:
"NLog is designed to swallow run-time exceptions that may result from
logging. The following settings can change this behavior and/or
redirect these messages."

Website:
"...less verbose is the internal log output."
Ron:
"...less verbose the intenrnal log output."

Website:
"To define a wrapper or compound target in the configuration file, we
simply nest the wrapped target inside the wrapping target element. You
can even wrap a wrapper target with no limit on the depth, so we can
modify the behaviour of a target in more than one way."
Ron:
"To define a wrapper or compound target in the configuration file,
simply nest a target node within another target node. You can even wrap
a wrapper target. There are no limits on depth."

--- Ron Grabowski <rongrabowski@...> wrote:

> I made it down to the Rules section. I'll finish up later.


-------------------------------------------------------
All the advantages of Linux Managed Hosting--Without the Cost and Risk!
Fully trained technicians. The highest number of Red Hat certifications in
the hosting industry. Fanatical Support. Click to learn more
http://sel.as-us.falkag.net/sel?cmd=lnk&kid=107521&bid=248729&dat=121642
_______________________________________________
Nlog-list mailing list
Nlog-list@...
https://lists.sourceforge.net/lists/listinfo/nlog-list

[Jaroslaw_Kowalski]

Thanks. I've updated the tutorial again.

Jarek
----- Original Message -----
From: "Ron Grabowski" <rongrabowski@...>
To: <nlog-list@...>
Sent: Thursday, June 01, 2006 2:07 AM
Subject: Re: [Nlog-list] New tutorial for NLog - help needed

> website:
> "Each rule can also be final..."
> Ron:
> "Rules are processed starting with the first rule in the list. When a
> rule matches, log messages are directed to target(s) in that rule. If a
> rule is marked as final, rules beneath the current rule are not
> processed."
>
> Website:
> "NLog provides include file mechanism for that..."
> Ron:
> "NLog provides an include file mechanism for that..."
>
> Website:
> "It's worth to notice that filename may include..."
> Ron:
> "It's worth noting that filename may include..."
> "It's worth noting that the file attribute, just like all attributes in
> NLog config file(s), may include dynamic values using the familiar
> ${var} notation."
>
> Website:
> "Configuration file is read automatically read at program startup."
> Ron:
> "The configuration file is read automatically at program startup."
>
> Website:
> "...it's sometimes desired to temporarily increase..."
> Ron:
> "...it's sometimes desirable to temporarily increase..."
>
> Website:
> "To allow for such reconfiguration, NLog can ..."
> Ron:
> The sentance would still make sense if the beginning part "To allow for
> such reconfiguration" were ommitted.
>
> Website:
> "Because NLog "eats" any exceptions that may occur during logging,
> application may not be notified about any problems."
> Ron:
> "Because NLog "eats" any exceptions that may occur during logging, an
> application may not be notified when problems occur."
> Some textbooks recommend not starting a sentance with the word
> 'because'. Here's another possible way of explaining things:
> "NLog is designed to swallow run-time exceptions that may result from
> logging. The following settings can change this behavior and/or
> redirect these messages."
>
> Website:
> "...less verbose is the internal log output."
> Ron:
> "...less verbose the intenrnal log output."
>
> Website:
> "To define a wrapper or compound target in the configuration file, we
> simply nest the wrapped target inside the wrapping target element. You
> can even wrap a wrapper target with no limit on the depth, so we can
> modify the behaviour of a target in more than one way."
> Ron:
> "To define a wrapper or compound target in the configuration file,
> simply nest a target node within another target node. You can even wrap
> a wrapper target. There are no limits on depth."
>
> --- Ron Grabowski <rongrabowski@...> wrote:
>
>> I made it down to the Rules section. I'll finish up later.
>
>
> -------------------------------------------------------
> All the advantages of Linux Managed Hosting--Without the Cost and Risk!
> Fully trained technicians. The highest number of Red Hat certifications in
> the hosting industry. Fanatical Support. Click to learn more
> http://sel.as-us.falkag.net/sel?cmd=lnk&kid=107521&bid=248729&dat=121642
> _______________________________________________
> Nlog-list mailing list
> Nlog-list@...
> https://lists.sourceforge.net/lists/listinfo/nlog-list
>

-------------------------------------------------------
All the advantages of Linux Managed Hosting--Without the Cost and Risk!
Fully trained technicians. The highest number of Red Hat certifications in
the hosting industry. Fanatical Support. Click to learn more
http://sel.as-us.falkag.net/sel?cmd=lnk&kid=107521&bid=248729&dat=121642
_______________________________________________
Nlog-list mailing list
Nlog-list@...
https://lists.sourceforge.net/lists/listinfo/nlog-list