Block comments - white space and line feeds

MWilliams

Hi there,

Seeing some interesting output from the documenter in HTML.

Block comments like the ones below:

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

Come out in the documentation as:

/*********************************/  /* 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

david connell

Hi Matt,
Where is this please? Is it in the descriptions?
Regards
David

MWilliams

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.

david connell

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

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

MWilliams

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

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

Hmmm I'm now changing my mind ... it works in FireFox ... but not in IE arggg .... !!!!

MWilliams

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

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

<span class='sqlScriptsComment'>/* This comment */</span>
<br />

but:

-- This comment

Will get the following:

<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.

david connell

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

MWilliams

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.