No, feel free to take the "remove HTML noise from documentation" baton and
run with it. The next big thing that **needs** to be done is fixing all the
URLs in the doc. They're basically all broken.
On Thu, Jun 27, 2013 at 7:23 PM, Blair Murri <os...@live.com> wrote:
> Rob,
>
> I've looked through the markdown and I believe I see how it all
> ties together. Pretty cool <smile/>
>
> It doesn't appear that the current documentation has any mention of this
> new markdown stuff, and also many of .md pages have embedded [x]html that
> could be "cleaned up" into markdown fairly easily and present an
> easier-to-grok baseline for future developers to more easily improve
> the documentation.
>
> Would you (or anyone else) have any objections to me updating
> the documents to describe how to write the documents using markdown (and
> maybe clean it up as I described)? Would I be stepping on anyone's toes
> (i.e. is anyone else doing this)?
>
> Blair
>
> ------------------------------
> From: os...@live.com
> To: wix-devs@lists.sourceforge.net
> Date: Wed, 26 Jun 2013 19:44:00 -0700
>
> Subject: Re: [WiX-devs] Infrastructure Improvement: help build
>
> I looked at the sources and it appears that we are using filesystem
> folders (and index.html.md files) to create the hierarchy. Please correct
> me if I'm wrong.
>
> ------------------------------
> From: r...@robmensching.com
> Date: Wed, 26 Jun 2013 14:29:28 -0700
> To: wix-devs@lists.sourceforge.net
> Subject: Re: [WiX-devs] Infrastructure Improvement: help build
>
> A flat list of almost 1,000 documents (remember all the XSD elements?)
> would be a very bad experience in the WiX.chm.
>
>
> On Wed, Jun 26, 2013 at 11:58 AM, Blair Murri <os...@live.com> wrote:
>
> Is a hierarchy possible or is the new TOC just a straight list? I haven't
> looked at the changes in depth yet.
>
> ------------------------------
> From: r...@robmensching.com
> Date: Wed, 26 Jun 2013 09:34:23 -0700
>
> To: wix-devs@lists.sourceforge.net
> Subject: Re: [WiX-devs] Infrastructure Improvement: help build
>
> 1. Ahh, I never use tabs (often typing Markdown in a text box and tabbing
> would leave the box) but I suppose it works. However, we don't use tabs in
> WiX toolset codebase today so I don't know that we should start.
>
> 2. Right, I forgot about the "after" metadata where you can say this
> document comes after another document in the TOC. By default documents are
> sorted by alphabetical order of the filename in the TOC. The TOC is built
> up from all the documents so we don't have a single file to deal with merge
> conflicts in. We'll see if it works well. I've liked it thus far during the
> migration.
>
>
> On Wed, Jun 26, 2013 at 5:27 AM, Blair Murri <os...@live.com> wrote:
>
> 1. According to http://daringfireball.net/projects/markdown/ either 4
> spaces or a tab at the beginning of the line demarks code, etc. (or
> backticks, of course).
>
> 3. How are you categorizing each page into the TOC if you are getting rid
> of the TOC? I assumed that would be via the metadata.
>
> ------------------------------
> From: r...@robmensching.com
> Date: Tue, 25 Jun 2013 23:16:05 -0700
> To: wix-devs@lists.sourceforge.net
> Subject: Re: [WiX-devs] Infrastructure Improvement: help build
>
>
> 1. Markdown uses for spaces to demark code snippets. Or you can wrap the
> code with `backticks`.
>
> 2. The "title" metadata is basically required (some dependencies snuck
> into the tools). If you don't specify a "layout" then no layout will be
> applied to the document. After that, you can put whatever you want in the
> metadata but it only matters if the "layout" uses it. In general, don't
> add lots of metadata because these documents also have to work in the
> website build which uses different layouts. That code shows up next... then
> I'm done with all this for a while. Whew.
>
>
> On Tue, Jun 25, 2013 at 11:50 AM, Blair Murri <os...@live.com> wrote:
>
> You are proposing that for markdown we use four spaces instead of tab
> chars. Just wanted to make sure that was the rule.
>
> Without going through the sources of your new tool, do you have a quick
> reference for the headers (such as title and layout in your example) that
> are supported?
>
> Blair
>
> ------------------------------
> From: r...@robmensching.com
> To: wix-devs@lists.sourceforge.net
> Date: Thu, 20 Jun 2013 05:05:46 +0000
> Subject: [WiX-devs] Infrastructure Improvement: help build
>
>
> There have been a few infrastructure improvements in the last six months.
> First, there was the move to git. Second, there is the new infrastructure
> for using xUnit.net testing. Now, I’m cleaning up the help build system
> because the web manual hasn’t been updated since WiX v3.7 moved to MSBuild.
> Additionally, writing documentation is beyond annoying since you have to
> write in perfect XHTML.
>
> I’ve been using DocPad (http://docpad.org/) a lot lately to build static
> sites and have been really happy with the functionality there. I’m moving
> the WiX toolset site (http://wixtoolset.org/) to DocPad to make it much
> easier to update the site. To get the help manual to integrate well with
> the rest of the site, the new help system borrows a lot of concepts from
> DocPad. That’s a good thing as long as you like Markdown. <smile/>
>
> New help content will look like this. Imagine a file:
> “src\chm\documents\overview\example.html.md”:
>
> ---
> title: Name in CHM table of contents or title of page on Web.
> layout: default
> ---
> # Example Topic H1
>
> This is a paragraph of text that explains stuff.
>
> ## Second Header using H2
>
> This is more paragraph text to introduce code example:
>
> <Wix>
> <!-- Indenting four spaces means you can just write code! --->
> <Feature Title='No & escaping necessary!' />
>
>
> That’s it. The same thing in current XHTML documentation is much longer
> and much harder to read and XML code snippets are horrible to write.
>
> Ultimately, my hope is that this further reduces the friction to writing
> and updating documentation so people will just go in and do it. If nothing
> else, the new system will get the web site content updated and it will work
> well together. Updating the current http://wix.sf.net/ site is a bunch of
> layered hacks.
>
> I hope to have my pull request coming soon that shows how it’ll all work
> very soon.
>
> Questions, comments and feedback?
>
> ------------------------------------------------------------------------------
> This SF.net email is sponsored by Windows: Build for Windows Store.
> http://p.sf.net/sfu/windows-dev2dev
> _______________________________________________ WiX-devs mailing list
> WiX-devs@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/wix-devs
>
>
> ------------------------------------------------------------------------------
> This SF.net email is sponsored by Windows:
>
> Build for Windows Store.
>
> http://p.sf.net/sfu/windows-dev2dev
> _______________________________________________
> WiX-devs mailing list
> WiX-devs@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/wix-devs
>
>
>
> ------------------------------------------------------------------------------
> This SF.net email is sponsored by Windows: Build for Windows Store.
> http://p.sf.net/sfu/windows-dev2dev
> _______________________________________________ WiX-devs mailing list
> WiX-devs@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/wix-devs
>
>
> ------------------------------------------------------------------------------
> This SF.net email is sponsored by Windows:
>
> Build for Windows Store.
>
> http://p.sf.net/sfu/windows-dev2dev
> _______________________________________________
> WiX-devs mailing list
> WiX-devs@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/wix-devs
>
>
>
> ------------------------------------------------------------------------------
> This SF.net email is sponsored by Windows: Build for Windows Store.
> http://p.sf.net/sfu/windows-dev2dev
> _______________________________________________ WiX-devs mailing list
> WiX-devs@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/wix-devs
>
>
> ------------------------------------------------------------------------------
> This SF.net email is sponsored by Windows:
>
> Build for Windows Store.
>
> http://p.sf.net/sfu/windows-dev2dev
> _______________________________________________
> WiX-devs mailing list
> WiX-devs@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/wix-devs
>
>
>
> ------------------------------------------------------------------------------
> This SF.net email is sponsored by Windows: Build for Windows Store.
> http://p.sf.net/sfu/windows-dev2dev
> _______________________________________________ WiX-devs mailing list
> WiX-devs@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/wix-devs
>
> ------------------------------------------------------------------------------
> This SF.net email is sponsored by Windows: Build for Windows Store.
> http://p.sf.net/sfu/windows-dev2dev
> _______________________________________________ WiX-devs mailing list
> WiX-devs@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/wix-devs
>
>
> ------------------------------------------------------------------------------
> This SF.net email is sponsored by Windows:
>
> Build for Windows Store.
>
> http://p.sf.net/sfu/windows-dev2dev
> _______________________________________________
> WiX-devs mailing list
> WiX-devs@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/wix-devs
>
>
------------------------------------------------------------------------------
This SF.net email is sponsored by Windows:
Build for Windows Store.
http://p.sf.net/sfu/windows-dev2dev
_______________________________________________
WiX-devs mailing list
WiX-devs@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/wix-devs
