Cant build html files

Topics: Bugs, General Questions, Sandcastle
Sep 5, 2007 at 3:06 PM
Edited Sep 5, 2007 at 3:08 PM
Hello,
im trying to create the html help files and im running in to a problem.

ive tried to build both from the external UI and from inside Visual Studio 2005

the error i run in to is:

Error BuildAssembler: A error ocurred while executing the transform '', on line 16, at position 120. The error message was: Startkoden 'meta' i linje 7 svarer ikke til slutkoden 'head'. Linje 16, position 120.
Info: Building topic Overload:_Home.LoadControl

and the last part that is on danish translates to: the StartCode 'meta' at line 7 does not match the EndCode 'head' at line 16, position 120.

this error comes around 3000 times in a row with various "Info: Building topic Overload:_Home.LoadControl" lines.

ive tried to look around in the various xml and xsl files to see if the code it tries to generate is somehow false.
ive tried to look around in my own files to see if i have any nested head meta tags but no luck, it doesnt say if this is an error in docproject or in my files and if in my files then what file,

can anyone please point me in the right direction on this one because i feel like ive run into a brick wall, im guessing its something stupid and simple, but still,

Thanks alot,
Anders
Sep 5, 2007 at 5:42 PM
Hi Anders,

Are you using the June 2007 CTP of Sandcastle?

I've never seen this build assembler error before, but the name of the transform file is missing from the error message, probably lost due to wiki formatting.

Knowing the name of the transformation would be useful.

- Dave
Sep 6, 2007 at 7:59 AM
yes im using Sandcastle June 2007 CTP

well, that is the exact error message, transform '', it doesnt say anything in between then '', ok, so i guess something went wrong, here..
i think i followed the instructions exactly, i had some problems with the part where you locate the dll file of the project and its supposed to automatically fill in the xml name in the textbox next to it, perhaps this is whats wrong, couldnt for my life get it to generate it...

hmm, ill try to start over with a very simple website and see if the same thing happens
Sep 6, 2007 at 8:21 AM
Hi,


well, that is the exact error message, transform '', it doesnt say anything in between then ''

In that case it sounds like a bug in build assembler. You should post this question to the MSDN forums.


i think i followed the instructions exactly, i had some problems with the part where you locate the dll file of the project and its supposed to automatically fill in the xml name in the textbox next to it, perhaps this is whats wrong, couldnt for my life get it to generate it...

Is there any particular reason why you're attempting to document an external source instead of a project reference? I recommend adding a project reference instead if possible.

The XML Documentation File text box is filled in automatically if you browse to an assembly that has an xml documentation file of the same name, but with .xml as the extension, located in the same directory.


hmm, ill try to start over with a very simple website and see if the same thing happens

That's a good idea. If you can reproduce the issue please let me know what steps you took.

Also, if you want to post the build output and any errors in the Application event log with DocProject as the source I'll take a look.

- Dave
Sep 6, 2007 at 8:24 AM
Edited Sep 6, 2007 at 8:25 AM
ok, that worked, so, problem must have been the lack of xml file.
i realized that the first time i tried the web deployment project hadnt built the xml file since i had loads of problems getting visual studio to build the deploy, the result was that i used the merge tool manually and it must have neglected to create the xml file, or something like that,

anyway, im gonna try to apply this on my other project and see if anything come out of it,

thanks,
Anders
Sep 6, 2007 at 8:45 AM
Hi Anders,

I've attempted to build DocProjects and DocSites without an xml documentation file and I've never seen this error, so I have to assume that it was something else that caused it.

I didn't realize that you were building help for a Web Site project, however. In that case you are correct that you must add the assembly output as an external source, as per the directions in How To Build Help For a Web Site Project.

Do you perhaps have some questions about the Web Deployment project and its useage that you would like to ask? Maybe the instructions aren't clear enough?

- Dave
Sep 6, 2007 at 8:57 AM
well, the only thing i failed to realize was that the deploy project needed to build the xml file aswell, although i dont think that that has got to do with poor instructions as much as lack of me using my brain :-)

and the main reason i failed i realize afterwards was not because i did anything in the setup wrong, it was because for some reason, what i did wrong i dont know, the deploy project wouldnt build, i got an error every time. but now i cleaned out the solution, did everything in the exact order, and it worked out, atm im just waiting for it to build the help, takes a while :-)

but the fact that you have managed to build without an xml file is interresting, makes me wonder.. seemed to obvious to me that thats what went wrong..
Sep 6, 2007 at 9:02 AM
Hi Anders,

In my tests I simlpy created a new DocProject and added a single external source (without any project references) and left the XML Documentation File field empty (actually, it added the xml file automatically so I had to manually clear the text box).

The project was able to build successfully. If you did anything differently, please let me know :)

- Dave
Sep 6, 2007 at 10:34 AM
yes, there is a diffrence,

my deploy project failed to build, i had to run the merge manually.
the xml file didnt even exist.
Sep 6, 2007 at 10:52 AM
Hi Anders,

I see, but in my test the xml document might as well have not existed anyway since it wasn't even being referenced by the DocProject :)

Your problems with the Web Deployment project should not have had a negative affect on DocProject. I assume that the real problem was either with the build assembler program or the DocProject software itself (possible bug, incorrect configuration settings, etc.), although you've certainly come across at least one issue with build assembler if it failed and didn't tell you the name of the transformation file!

- Dave
Sep 6, 2007 at 12:42 PM
i now succeded in creating the help files and have one small question,
I cant see the class and method descriptions

the one that looks like this:

'''<summary>this functions does bla bla</summary>
Public Function bla()

End Function

is this a setting somewhere, and if so, where?
Sep 6, 2007 at 1:08 PM
Hi Anders,

Check the buildhelp\assembler\Comments folder for the xml documentation file (you'll have to Show All Files to see the buildhelp folder in the project).

If the file is there then open it and make sure your comments are inside. If the file isn't there then make sure it was added to the external sources dialog along with the assembly being documented.

There is no specific setting that you must enable. If the file has the comments and it's located in the appropriate folder then Sandcastle should use it automatically when it generates the help topics.

Let me know what you find.

- Dave
Sep 6, 2007 at 1:16 PM
Hello,

im not entirely sure i know what you mean, there is 2 files there, Project_Deploy.xml and project.xml, none of them contains my comments,

what i thought it would do is add them to the .chm file?

like:

'function that does bla bla
class1.bla

like a normal description of .net built in functions it should show the summary in the help file right?

Sep 6, 2007 at 1:35 PM
Hi Anders,

I assume that the Project_deploy.xml file was generated by your Web Deployment project? If you found it in the Comments folder then that means Sandcastle should have read it and applied the comments to the appropriate help topics as they were generated. The reason why you don't see any comments in the resultant .CHM file is because, as you said, your comments do not appear in the Project_deploy.xml file.

By any chance were the comments added to classes in the App_Code folder? The instructions in How To Build Help For a Web Site Project do not apply to those files - only .aspx pages. Unfortunately, generating an xml documentation file for classes in the App_Code folder and including it in DocProject isn't easy (and might not even be possible), so I recommend moving those classes to a new Class Library project. A new class library project can be referenced easily by your web site project and your DocProject or DocSite using a project reference.

- Dave