How might I troubleshoot a Sandcastle-generated, defective, MS-Word file?

203 views Asked by At

enter image description here

I've run into this before but it was years ago (Sandcastle 4.9 and MSVS 2012). Does anybody have any idea of how to troubleshoot such a diagnostic (that's my explicit question)?

Opening the .docx file in, say, Notepad or Notepad++ is of no use (the file is usually too large for Notepad, and even if Notepad++ can open it, the delay is agonizing). Don't bother with the Sandcastle log, even at verbose level, in this case, it thinks it has done just a grand job! After all, it did produce the .docx file without suffering a cruel death or catching fire.

Steps to Reproduce

  1. Build with MSVS, producing the documentation XML
  2. Run Sandcastle against the XML (and DLL or whatever) to make an open XML document (filetype .docx)
  3. Open that .docx file
  4. Scream in frustration when you see the diagnostic, or, if you don't, count yourself lucky

In the meantime, as work-arounds, I've found the following C# XML documentation elements seem to trigger this behavior:

  1. Bounded seealso

    <seealso cref="item">Don't do this!</seealso>  
    

    use only

    <seealso cref="item"/>
    
  2. para

    <para>...</para>  
    

    this construct often works ... but when it doesn't...
    A workaround is to use

    <br/>  
    

    instead of the leading para tag and omit any trailing tag

0

There are 0 answers