How to use

Oct 8, 2008 at 12:29 PM

Apologize for this type of question, but can you please explain the basics.
I want to include a latex based equation in the <remarks/> section of my source code XML documentation.
I downloaded Latex.
I downloaded and sucessfully installed sandcastle, shfb, etc.; right now I can sucessfully produce documentaion.

With respect to your code, what should I compile, how to interface to Latex, which tags to include in my source.
Overall, can you please provide explanation on the basics / getting started.

Thank you,
- E

Coordinator
Oct 8, 2008 at 2:38 PM
>>EdStone: Apologize for this type of question, but can you please explain the basics.
Why the apology? This forum is here for questions and discussions, so feel free to ask any question anytime.
The components are still under development, so there is currently no documentation except comments in the sample configuration files - sorry.

>>EdStoneI downloaded Latex.
It is MikTeX (http://miktex.org/), and are you comfortable with LaTeX?

>>EdStone: I downloaded and sucessfully installed sandcastle, shfb, etc.; right now I can sucessfully produce documentaion.
I have not used it with SHFB, so I will need time to investigate how you can do it - I will get back to you.
Is it late if I provide the information by this weekend (Oct 11)?

>>EdStone: With respect to your code, what should I compile, how to interface to Latex, which tags to include in my source.
First compile and run the sample in the CTP release, it contains examples and illustrations for both Reference and Conceptual helps.
In particular, look at the Equation.cs file in the TestLibrary, it provides illustrative examples in the <remarks/>.
You do not need the SHFB to run the sample, just open the solutions in VS.NET, compile and run. Please let me know if you have any problem with this.

>>EdStone: Overall, can you please provide explanation on the basics / getting started.
I will provide one here for you, it does not require anything special if you know how to use LaTeX.

Best regards,
Paul.
Oct 8, 2008 at 3:34 PM
To integrate custom build components with SHFB, you can create a component configuration file that tells SHFB how to use it if one isn't supplied with the components already.  See the Creating a Component Configuration File topic under the Custom Build Components section of the help file for details.  Once created, place the component assembly and the configuration file in the .\BuildComponents folder under the main SHFB installation folder.  Restart SHFB, open a project, select the ComponentConfigurations property and, if the config file is correct, you should see the new component listed on the left.  Double-click it to add it to the project.  The level of configuration support depends on whether or not the component provides an interactive configuration method or not.  If a configure method is defined, it can invoke a dialog to edit the configuration in an user-friendly fashion.  If not, you can still edit the raw XML configuration but you'll need to know more about the component configuation and what elements are needed.

Eric
Coordinator
Oct 8, 2008 at 6:03 PM
Edited Oct 8, 2008 at 6:04 PM
>>Eric: To integrate custom build components with SHFB, you can create a component configuration file that tells SHFB...
Thanks for the input, I will look into it.

>>Eric: The level of configuration support depends on whether or not the component provides an interactive configuration method or not.
If you mean SHFB specific extensions, no. We do not have any plan to add Windows Forms dependency or add any tool specific extensions to the Components package.
Configurations will be handled through Common/Configurations classes, and Windows Forms controls for creating/editing the configurations in Controls package (a tool can choose to use these or create its own).

Best regards,
Paul.
Oct 8, 2008 at 7:22 PM

The way I designed my components is to make interactive configuration of them tool-agnostic.  All SHFB looks for in a component, mine or anyone else's, is a static configuration method that it can call with the current configuration XML and that returns the edited configuration XML.  Any other tool such as DocProject or your tools is able to call it too and it will work.  The tool consuming the component is not bound to any particular version of it and doesn't have to add support for any specific designers I may create and that may change in the future.  How sophisticated it gets once inside the configuration method is up to the component producer.  Your build component could invoke any designers it supports distributed with the component or use a simple Windows Forms dialog box.

Eric

 

Coordinator
Oct 8, 2008 at 11:23 PM
Edited Oct 8, 2008 at 11:24 PM
>>Eric: The way I designed my components is to make interactive configuration of them tool-agnostic.
I do not think so. The very design of it assume
1. Every tool is going to be .NET based,
All that is needed is to modify or create XML configuration file for BuildAssembler (a command line tool) so whether I use Eclipse or MFC-based environment is not an issue here.

2. Every tool is going to be popping up Windows Forms Dialog for editing its configuration,
Every tool decides how best to create UI that is convenience and easy to use, popping up dialog may not be fit every solution.

3. Every tool will do configuration in a particular way.
We work on two build libraries, Lite Builders and a more extensive Builder library later.
Each of these considers editing of configuration files in completely different ways.

4. Every tool will need to configure only the custom build components that way, not the standard components.
We have decided to keep the custom build components as just what they are, similar to the Sandcastle components.
Configurations will be provided for both our components and Sandcastle components in a similar way, and in a separate package. If a tool finds our method of configuration to be fitting to its model, it uses it; otherwise it creates its own.

DocProject is also releasing component base library so that components will better work with DocProject, and I do not know if Dave finds your approach convenient to use. But according to it documents, the components based on it will work with both SHFB and DocProject. We do not find this convenient either, since we are not creating components for SHFB, DocProject or our tools in particular.

Best regards,
Paul.