SHFB Forum Rss Feed

New Post: Add images in XML doc

Guson — Tue, 21 May 2013 06:18:13 GMT

I certainly did, the CopyToMedia is something else, I check it later. Now this is the way to do;-)

Use images, not referenced by MAML topics

Import the [images]-folder into shfb Project Explorer, not referenced by MAML topics:

Select Add and Existing Folder... from tree context menu, select the [images]-folder
For each image-file, set BuildAction from Image to Content
In shfb, push the Build the help file button

After the build, you have a <appname>.chm help file, with images. Easy :-).

Regards
/Jonas

New Post: Add images in XML doc

EWoodruff — Mon, 20 May 2013 16:33:45 GMT

I think you missed what I said in my first response. If these the images are not being used in MAML topics, just set the BuildAction in the SHFB project to Content and place them in an Images folder off the root of the project. They'll get copied into the working folder automatically and compiled into the help file.

Eric

New Post: Add images in XML doc

Guson — Mon, 20 May 2013 12:06:51 GMT

Batch for all help file formats

@ECHO OFF
:: 1. In shfb, push the "Build the help file" button
:: 2. In "Build Output" wait for the "Clearing working folder..." output
:: 3. Run this batch file

REM Comment/uncomment in Build selected help file formats
REM HTML Help1 (CHM)
xcopy images\*.* help\Working\Output\HtmlHelp1\images\*.* /q /y
REM MS Help 2 (HxS)
REM xcopy images\*.* help\Working\Output\MSHelp2\images\*.* /q /y
REM MS Help Viewer (MSHC)
REM xcopy images\*.* help\Working\Output\MSHelpViewer\images\*.* /q /y
REM Website (HTML/ASP.NET)
REM xcopy images\*.* help\Working\Output\Website\images\*.* /q /y

I havent verifyed MS help 2 and MS Help Viewer.

New Post: Add images in XML doc

Guson — Mon, 20 May 2013 10:54:50 GMT

Yes! I did'it, with MS help1 file. ;-)
I did a longshot, when building the help file.

Create a batch containing:

@ECHO OFF
xcopy images\*.* help\Working\Output\HtmlHelp1\images\*.* /q /y

Build help file

In shfb, push the Build the help file button
In Build Output wait for the Clearing working folder... output
Run the batch file

After the build, you have a <appname>.chm help file, with images. Not so easy, but the result was correct.

New Post: Add images in XML doc

Guson — Mon, 20 May 2013 10:11:23 GMT

Hi!
The help file is currently only for internal usage, so I prefere MS Help1 file (one file, easy to use).

New file structure

I changed my file structure, if I want to produce other help-formats. I imported the [images]-folder into shfb Project Explorer, and marked the images as CopyToMedia=True. I use .NET Framework 4.5 in Build settings.

[appname]\
    [doc]\
        [help] (shfb-output, temprary folder)
        [images]\ (images-folder, to use in shfb-build)
        <appname>.shfbproj
        <appname>.chm (copied from [help]-folder)
    [projname]\ (the VS project)
    <appname>.sln

And the [help]-folder (shfb-output) is only used as a temprary folder.

Source code documentation

The path is relative to the [help] (shfb-output) folder, i guess after your description.
The images is referenced from XML documentation in source code, like this:

<img src="..\images\ControlBox.png" alt="ControlBox Class Diagram" />

SHBF builds

I have tryed all build formats, and the only one that I can get to work is Website (HTML/ASP.NET), if I manually copy the [images]-folder into the [help]-folder, after a shfb-build. And its okey with a html help. I could do a batch, containing:

@ECHO OFF
xcopy images\*.* help\images\*.* /q /y
%SystemRoot%\Microsoft.NET\Framework\v4.0.30319\msbuild.exe <appname>.shfbproj
pause
help\Index.html

And in shfb proj change to include the [projname]<projname>.csproj insted of <appname>.sln, because I get some error running the batch, no problen running in shbf gui. (SHFB : error BE0042: You must specify at least one documentation source)

MAML-pages

I have not tryed adding/using MAML-pages, but it maybe a better aproach, then I could extend code documentation, with custom Welcome-, History-, Class description-pages, before the code documentation.

New Post: Add images in XML doc

EWoodruff — Fri, 17 May 2013 19:32:30 GMT

The basePath only relates to the code block component which has no bearing on how images are displayed or referenced. In relation to imported code blocks, the base path is the project folder.

Bear in mind that when you add an image to a SHFB project, it's default BuildAction is set to Image with the assumption that it will be used in MAML topics. With that build action, it only gets copied if referenced in a MAML topic and will end up in the Media\ folder. Setting the CopyToMedia property to true will force it to always get copied to the .\Media folder even if not referenced in MAML topics.

If your intent is to simply use it from XML comments, set its BuildAction property to Content so that it is always copied to the output folder. If located at the root, it will get copied to the root of the help content. If in a subfolder, it will get copied to a like-named subfolder in the help content. From there, the information in the FAQ entry is correct. Use either a relative path (..\Image.png) or relative path with subfolder (..\Images\Image.png) to access it.

However, if producing MS Help Viewer output, the above may not work as I recall since the viewer modifies the URLs. I'd have to try it and see if there's a way to make it work.

Eric

New Post: Add images in XML doc

Guson — Fri, 17 May 2013 14:02:10 GMT

Hi!
I have used SHFB, to produce code documentation for a while, and now I want to add pictures like class diagram and so on.

SHFB - Project Properties

In SHFB project settings I have:
[Paths/Output Paths/Help content output path] = doc\
(Warning: The output folder will be erased, when building a web-site)

My file structure

[appname]\
    [doc]\ (shfb-output)
    [img]\ (images)
    [projname]\ (the VS project)
    <appname>.shfbproj
    <appname>.sln

Description

[] - folder
<> - file
() - comment

Questions

(From SHBF documentation) "The path is relative to the basePath configuration element."
Q: What is the "basePath"?

doc
doc\Working\Output\HtmlHelp1
projname

I cant get it to work, only placeholder of image.

<img src="ControlBox.png" alt="ControlBox Class Diagram" />
<img src="../ControlBox.png" alt="ControlBox Class Diagram" />
<img src="../img/ControlBox.png" alt="ControlBox Class Diagram" />

Q: How to add image-path(s) to shfbproj-file
Why:

I would prefere to specify (a list of) image-folder(s), when runing the shfb project
In XML doc of code-file only use file name, <img src="ControlBox.png" alt="ControlBox Class Diagram" />

Q: List of supported image formats
?: (gif, jpg, png)

Links

SHBF - Discussions

SHFB - FAQ

New Post: Caching to speed up FillNode.aspx

Takajalka — Tue, 14 May 2013 23:01:46 GMT

I'll have to ask whether my employer is willing to contribute the changes.
If not, someone else can perhaps implement a similar solution.

New Post: Markdown Support

EWoodruff — Mon, 13 May 2013 19:33:33 GMT

Nobody has as far as I know. The main task would be creating a presentation style that generated the output in markdown format. Depending on how far you wanted to take it, some work may also need to be done on a few of the build components since they all assume HTML output. For example, the reference link components would need to be updated to support outputting the links in the markdown format rather than as HTML anchor links. If generating API topics, the syntax generators use CSS styles to colorize the code in the syntax sections so they may need to change as well.

Eric

New Post: Caching to speed up FillNode.aspx

EWoodruff — Mon, 13 May 2013 19:17:56 GMT

If you'd care to share your changes, I'd be happy to merge them into a future release of SHFB. You can open a work item here and attach them to it or e-mail me the changes. My e-mail address is in the About box in the standalone GUI and in the footer of the pages in the help file.

Eric

New Post: BUILDASSEMBLER : error : The target attribute is missing or has no value

EWoodruff — Mon, 13 May 2013 19:12:10 GMT

The error has been converted back to a warning for the next release with a better message that gives a hint as to the cause of the problem.

Eric

New Post: Markdown Support

ssmith — Mon, 13 May 2013 17:27:25 GMT

Has anybody modified Sandcastle to produce markdown, rather than HTML, output?

New Post: Caching to speed up FillNode.aspx

Takajalka — Mon, 13 May 2013 16:02:27 GMT

A better solution:

Define classes for the HelpTOC and HelpTOCNode elements, and load WebTOC.xml to them with XmlSerializer. Take all the nodes that have IDs, and collect them to a Dictionary<Guid, TocNode> instance. Insert this dictionary into Page.Cache, with the appropriate CacheDependency. On each request, find the correct node from the dictionary, and show its children. Because Dictionary<TKey, TValue> is thread-safe for multiple readers, no locking is needed after initialization.

After the application pool has been restarted, the first use of FillNode.aspx takes about 880 ms in this solution. That includes the time XmlSerializer spends generating and compiling the serialization assembly. Subsequent requests typically take only two milliseconds, so the IIS output cache is no longer useful. If the WebTOC.xml file is modified, then FillNode.aspx automatically reloads it with the previously generated serialization assembly; this takes about 430 ms.

The initialization time could be improved by replacing XmlSerializer with hardcoded methods that use XmlReader, but 880 ms is already fast enough for something that runs perhaps once a day, and custom deserialization would make later maintenance more expensive.

New Post: BUILDASSEMBLER : error : The target attribute is missing or has no value

rp — Mon, 13 May 2013 13:38:54 GMT

My problem was that I had used 'member' instead of 'cref' as the attribute name.
Without this thread I would never have found the cause of the problem.

A more helpful error message, and the option to make it just a warning, would be much appreciated.

New Post: Caching to speed up FillNode.aspx

Takajalka — Fri, 10 May 2013 21:43:25 GMT

With a 12-megabyte WebTOC.xml, the single-user response times from FillNode.aspx are typically between 500 and 600 milliseconds, as shown by the Web Console in the Firefox browser. This is because FillNode.aspx parses the entire file to a new XPathDocument instance on each request.

If I change FillNode.aspx to cache the XPathDocument instance between requests, then the single-user response time is only around 120 milliseconds; typically between 115 and 125. This is with a CacheDependency on the file and lock (toc) { ... } around everything that accesses the XML nodes after they have been read from the cache. (Although XPathDocument is read-only on the surface, it is not thread-safe.) Such serialization may be bad for scaling to hundreds of simultaneous users but I suspect the current code wouldn't work too well in that situation either. For better parallelism, one might consider setting up a pool of XPathDocument instances, or using the thread ID or processor ID as part of the cache key.

Far better savings can be achieved by configuring IIS user-mode output caching to consider only the "Id" and "topic" query string variables and ignore the "hash" variable. If the data is already in the cache, then the response time is typically only 1 or 2 milliseconds. However, each cache entry only covers one parent node, and the output cache tends to discard rarely-used entries pretty soon after the last use. Thus, for the best performance, the IIS output cache should be used together with XPathDocument caching.

New Post: Code in `blocks not keeping indentation spacing`


JHolland — Fri, 10 May 2013 20:02:11 GMT
Thank you so much for your quick response!




I have discovered that this is an issue because I am using WCFExtras+ to pull the comments into a generated service contract, and that tool is eliminating all my formatting.  I apologize for wasting your time with my question.




Thanks again!



New Post: Token within Token?
EWoodruff — Fri, 10 May 2013 19:31:47 GMT
I finally got around to checking this and nested tokens are working as expected.  Typically, if a token is not found, you'll get no output at all, not just the token name.  You didn't say whether this was in a MAML topic or in XML comments.  If in XML comments, you do need to add the API Token Resolution build component to the project in order for the tokens to get replaced.




Eric




New Post: Code in  blocks not keeping indentation spacing

EWoodruff — Fri, 10 May 2013 19:24:46 GMT
As long as it's nested within an example element, it should render just fine.  If you've got the Indent HTML project option enabled, turn it off as it will cause problems with the format, though it usually only affects the first line.  That option is for debugging the output and should be typically left disabled.




Eric




New Post: Code in  blocks not keeping indentation spacing

JHolland — Fri, 10 May 2013 18:40:34 GMT
I have tried several different variations in my code block to try to get the output help documentation to have formatted C# code, but they all end up with the entire code block left aligned.  Is there a way to get the spacing to persist to the generated help file?




e.g.

/// <code lang="C#">
/// using MyClass.ServiceContracts;
/// class Program
/// {
///     static void Main(string[] args)
///     {
///         MyClient _myClient = new MyClient();
///         MyRequest _myRequest = new MyRequest();
///         _myClient.performRequest(_myRequest);
///     }
/// }
/// </code>


comes out as:




using MyClass.ServiceContracts;


class Program


{


static void Main(string[] args)


{


MyClient _myClient = new MyClient();


MyRequest _myRequest = new MyRequest();


_myClient.performRequest(_myRequest);


}


}




New Post: Website ouput: Merge documentation from different sources
EWoodruff — Wed, 08 May 2013 19:29:55 GMT
A build component is probably not necessary. Reference links are generated by ResolveReferenceLinksComponent2 and ResolveConceptualLinksComponent.  By default, they contain no path, just the GUID plus a ".htm" extension.  ResolveReferenceLinksComponent2 supports an href-format attribute that defines the local link format.  ResolveConceptualLinksComponent supports a url attribute on the target elements that defines the link format.




SHFB does not use nor does it expose a way to alter those attributes.  In order to change them, you could write a plug-in that alters the configuration files to add the appropriate attributes to the necessary configuration elements.  I haven't looked to closely at the required format nor have I documented them yet so you'd have to poke around in the build component source code to figure out the required value format.  There's a topic in the SHFB help file on writing plug-ins so that would be the place to look for into on writing the actual plug-in.




Eric