Red Gate forums :: View topic - Block comments - white space and line feeds
Return to www.red-gate.com RSS Feed Available

Search  | Usergroups |  Profile |  Messages |  Log in  Register 
Go to product documentation
SQL Doc 1
SQL Doc 1 forum

Block comments - white space and line feeds

Search in SQL Doc 1 forum
Post new topic   Reply to topic
Jump to:  
Author Message
MWilliams



Joined: 20 Mar 2007
Posts: 8

PostPosted: Tue Mar 20, 2007 3:36 pm    Post subject: Block comments - white space and line feeds Reply with quote

Hi there,

Seeing some interesting output from the documenter in HTML.

Block comments like the ones below:

Code:

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


Come out in the documentation as:

Code:

/*********************************/  /* 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
Back to top
View user's profile Send private message
david connell



Joined: 21 Nov 2005
Posts: 207

PostPosted: Tue Mar 20, 2007 6:29 pm    Post subject: Reply with quote

Hi Matt,
Where is this please? Is it in the descriptions?
Regards
David
Back to top
View user's profile Send private message
MWilliams



Joined: 20 Mar 2007
Posts: 8

PostPosted: Tue Mar 20, 2007 6:35 pm    Post subject: Reply with quote

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.
Back to top
View user's profile Send private message
david connell



Joined: 21 Nov 2005
Posts: 207

PostPosted: Tue Mar 20, 2007 7:11 pm    Post subject: Reply with quote

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:

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
Back to top
View user's profile Send private message
MWilliams



Joined: 20 Mar 2007
Posts: 8

PostPosted: Wed Mar 21, 2007 9:51 am    Post subject: Reply with quote

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
Back to top
View user's profile Send private message
MWilliams



Joined: 20 Mar 2007
Posts: 8

PostPosted: Wed Mar 21, 2007 10:12 am    Post subject: Reply with quote

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.
Back to top
View user's profile Send private message
MWilliams



Joined: 20 Mar 2007
Posts: 8

PostPosted: Wed Mar 21, 2007 10:18 am    Post subject: Reply with quote

Hmmm I'm now changing my mind ... it works in FireFox ... but not in IE arggg .... !!!!
Back to top
View user's profile Send private message
MWilliams



Joined: 20 Mar 2007
Posts: 8

PostPosted: Wed Mar 21, 2007 10:26 am    Post subject: Reply with quote

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.
Back to top
View user's profile Send private message
MWilliams



Joined: 20 Mar 2007
Posts: 8

PostPosted: Wed Mar 21, 2007 11:08 am    Post subject: Reply with quote

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:
<span class='sqlScriptsComment'>/* This comment */</span>
<br />

but:

-- This comment

Will get the following:
Code:
<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.
Back to top
View user's profile Send private message
david connell



Joined: 21 Nov 2005
Posts: 207

PostPosted: Wed Mar 21, 2007 11:52 am    Post subject: Reply with quote

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
Back to top
View user's profile Send private message
MWilliams



Joined: 20 Mar 2007
Posts: 8

PostPosted: Wed Mar 21, 2007 12:59 pm    Post subject: Reply with quote

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.
Back to top
View user's profile Send private message
Display posts from previous:   
Reply to topic All times are GMT + 1 Hour
Page 1 of 1

 
You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum


Powered by phpBB © 2001, 2005 phpBB Group