What are the challenges you face when working across database platforms? Take the survey
Options

Block comments - white space and line feeds

MWilliamsMWilliams Posts: 9
edited March 21, 2007 7:59AM in SQL Doc Previous Versions
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

Comments

  • Options
    Hi Matt,
    Where is this please? Is it in the descriptions?
    Regards
    David
  • Options
    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.
  • Options
    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
  • Options
    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
  • Options
    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.
  • Options
    Hmmm I'm now changing my mind ... it works in FireFox ... but not in IE arggg .... !!!!
  • Options
    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.
  • Options
    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.
  • Options
    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
  • Options
    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.
Sign In or Register to comment.