Block comments - white space and line feeds

Documents SQL Server 2000, 2005 and 2008 databases.


Moderators: David Atkinson, david connell, Charles Brown

Block comments - white space and line feeds

Postby MWilliams » Tue Mar 20, 2007 3:36 pm

Hi there,

Seeing some interesting output from the documenter in HTML.

Block comments like the ones below:

Code: Select all
/*********************************/
/*      This is a title          */
/*      ---------------          */
/* Some descriptive text here    */
/* that will explain stuff       */
/*********************************/


Come out in the documentation as:

Code: Select all
/*********************************/  /* This is a title */ /* --------------- */ /* Some descriptive text here */ /* that will explain stuff */ /*********************************/


i.e. line feeds and white space are not treated literally. Any ideas on something that can be done to make these more readable?

Thanks,

Matt
MWilliams
 
Posts: 8
Joined: Tue Mar 20, 2007 12:59 pm

Postby david connell » Tue Mar 20, 2007 6:29 pm

Hi Matt,
Where is this please? Is it in the descriptions?
Regards
David
david connell
 
Posts: 167
Joined: Mon Nov 21, 2005 10:12 am

Postby MWilliams » Tue Mar 20, 2007 6:35 pm

It is in the 'SQL Script' section of the stored proc, trigger etc.

These style comments are there for people when they are reviewing/modifying code on the database ... it would be really nice therefore if they were as readable in the docs.

Hope that answers the question ... if not then just let me know.

Thanks,

Matt.
MWilliams
 
Posts: 8
Joined: Tue Mar 20, 2007 12:59 pm

Postby david connell » Tue Mar 20, 2007 7:11 pm

Hi Matt,
I copied and pasted your code straight into my SQL Script for a Stored Proc called bob.
I then generated the following output in a CHM & straight HTML using SQL Doc 1.1
Code: Select all
CREATE procedure [dbo].[bob]
@b1 int = null
as


/*********************************/ 
/* This is a title */ 
/* --------------- */ 
/* Some descriptive text here */ 
/* that will explain stuff */ 
/*********************************/ 

select 1 from syscomments

declare @b2 int

select @b2 = count(*) from syscomments



There are two issues from what I can see.
Issue 1) Where are the cariage returns?
Issue 2) Space padding has gone wrong

Re issue 1... What does the rest of your SQL Script look like? I wonder if the editor has only put in line feeds and not cariage returns?
Issue 2.. I think that the missing spaces could be SQL Doc problem. I will raise this as a bug.

Regards
David
david connell
 
Posts: 167
Joined: Mon Nov 21, 2005 10:12 am

Postby MWilliams » Wed Mar 21, 2007 9:51 am

Thanks for that ... interesting to see the result you got.

I'll investigate the Carriage return / line feed difference and see what comes up.

The white space thing is really a HTML thing (it will ignore multiple whitespaces together) ... might be possible to fix simply in the stylesheet, I've not checked. The other alternatives I can think of are just way to ugly to mention!!!

Matt.

PS Just done a quick search for stylesheets and whitespace ... there looks like there might be something I can test ... I'll let you know the results
MWilliams
 
Posts: 8
Joined: Tue Mar 20, 2007 12:59 pm

Postby MWilliams » Wed Mar 21, 2007 10:12 am

I made the following alteration to the Master.css:

.sqlScriptsComment
{
color: green;
white-space: pre;
}

This sorted everything out ... linefeeds and whitespace. Introduced a few extra blank lines elsewhere ... but that is of much less importance.

Thanks for the help,

Matt.
MWilliams
 
Posts: 8
Joined: Tue Mar 20, 2007 12:59 pm

Postby MWilliams » Wed Mar 21, 2007 10:18 am

Hmmm I'm now changing my mind ... it works in FireFox ... but not in IE arggg .... !!!!
MWilliams
 
Posts: 8
Joined: Tue Mar 20, 2007 12:59 pm

Postby MWilliams » Wed Mar 21, 2007 10:26 am

OK ... so the difference between IE and FireFox is the Carriage return / line feed issue which should be easy for me to fix.

The 'padding' however is observed in both ... so after I've played around a little with the actual text to make sure the the correct lf/cr is being used it should be a workable solution.

Thanks,

Matt.
MWilliams
 
Posts: 8
Joined: Tue Mar 20, 2007 12:59 pm

Postby MWilliams » Wed Mar 21, 2007 11:08 am

More playing ... and I've discovered something else.

The HTML generated by the different comment type (block comments '/**/', or line comments '--') is different. This is what is causing extra line feeds to be introduced when the 'white-space: pre;' line is put into the master.css.

eg.

/* This comment */

Will get the following line of html
Code: Select all
<span class='sqlScriptsComment'>/* This comment */</span>
<br />

but:

-- This comment

Will get the following:
Code: Select all
<span class='sqlScriptsComment'>-- Comment here
</span>
<br />

(Notice that the line feed at the end of the comment, has been introduced into the span ... resulting in two line feeds when rendered in the HTML!!)

Interested to hear what you think.

Thanks,

Matt.
MWilliams
 
Posts: 8
Joined: Tue Mar 20, 2007 12:59 pm

Postby david connell » Wed Mar 21, 2007 11:52 am

Hi Matt,
Thanks for pointing out this difference... I think that there is an issue in what a comment means... The block comment does not include the \"new line\" because it's not included in the comment. However the line comment has decided to include the \"new line\" return because it's part of the line. Or as you have said, is it? I will have to go and ask someother people.

OK I have just asked one of the SQL Refactor team, and they told me that \"new lines\" should be considered part of the line comment. This is what SQL Server does. However he also said that only \"new lines\" are really new lines in SQL Server and \"cariage returns\" should be ignored because that's what SQL Server could do under certain collations. He did say that it was a little unclear exactly what some of these cases meant.

I have now spoken with Robert one of the developers on SQL Doc. He did not agree with the adding of the white-space: pre; tag in your CSS . (His argument was that the viewer should automatically cater for word wrap etc and not interpret the data directly.)
However then it leaves the issue of spaces. So he felt that SQL Doc should have escaped the spaces correctly in the comments. Which it does not do.

Personally I would use the descriptions to put these type of comments in. Because you can then comment anything from Functions, to Tables to .... However \"new lines\" are not correctly formatted in SQL Doc 1.1.

So in summary I will put forward that spaces and tabs in comments are escaped.

Regards
David
david connell
 
Posts: 167
Joined: Mon Nov 21, 2005 10:12 am

Postby MWilliams » Wed Mar 21, 2007 12:59 pm

David,

Thanks for all the work on that ... and for all the input from the various members of the team. Completely agree that the escaping method is the 'correct' way to go (I noticed that this is adopted elsewhere) so will look forward to it appearing.

Cheers,

Matt.
MWilliams
 
Posts: 8
Joined: Tue Mar 20, 2007 12:59 pm


Return to SQL Doc 1

Who is online

Users browsing this forum: No registered users and 0 guests