TypeMetal for Xcode docsets?

Welcome! Forums TypeMetal Support TypeMetal for Xcode docsets?

This topic contains 11 replies, has 2 voices, and was last updated by  Uli Zappe 2 years, 1 month ago.

Viewing 12 posts - 1 through 12 (of 12 total)

  • Author

    Posts

  • #1046

    Reply


    Uli Zappe

    Hi,</p>
    <p>I stumbled accross TypeMetal recently when looking for a Cocoa WYSIWIG web site builder, which it obviously isn’t.</p>
    <p>However, after being impressed by the application for what it is and scanning through the documentation, I wonder whether TypeMetal might be a suitable tool for another task for which I’ve been looking for a tool for a long time, and this is creating Xcode docsets.</p>
    <p>I’m aware of the tools that construct such docsets from apropriately formatted comments in the source code, but personally, I strongly dislike mixing up the source code and the documentation. My comments in the source code target those who might edit this source code, whereas the Xcode docset should target those who just want to use the objects/frameworks, introduction and illustrative images included. Therefore, I want to write my documentation separately in an appropriate editor.</p>
    <p>So, my question is if you would consider TypeMetal (probably with a snippet set dedicated to this task and Apple’s pertinent CSS files) an adequate application for this task?

    #1050

    Reply


    Troy Stephens

    Keymaster

    Hi Uli,

    In theory at least, you could write the docset’s constituent .html files using TypeMetal, which is a fully general HTML editor where the .html file’s content is concerned. (<head> editing is currently limited to <title> and optional stylesheet and snippet set <link> elements.) But I don’t have experience creating Xcode docsets, so I can’t speak to other aspects of the process. I have used TypeMetal to write the content for TypeMetal’s own OS X Help bundle (mirrored online as the TypeMetal User Guide), which is a somewhat similar proposition, in that there’s surrounding file system structure conventions and indexing involved, and that has worked out well for me. (I’ve of course had to use Apple’s help indexer tool to do the indexing work.)

    It would certainly be nice to have intrinsic and more comprehensive support for building structured HTML-based projects such as Xcode docsets in the future.

    Thanks for the question, and I hope this answer helped!
    Troy

    #1052

    Reply


    Uli Zappe

    Hi Troy,

    thanks for your reply!

    I tink I’ll just go ahead and buy TypeMetal now and give it a try the next time I need to create an Xcode docset.

    I currently don’t know when this will be, but when I’ll do it, I’ll come back here and report how it went.

    #1054

    Reply


    Troy Stephens

    Keymaster

    Thanks, Uli! I appreciate the support, and the opportunity to learn from your experiment — would love to hear how it goes!

    In its current incarnation, TypeMetal’s goal has been to make the content writing process easier and more efficient. Content assembly is another worthy challenge, that would be interesting to address in the future.

    Troy

    #1206

    Reply


    Uli Zappe

    As promised, I want to give some feedback after trying to use TypeMetal for Xcode like documentation.</p>
    <p>Unfortunately, I didn’t come very far. The problem is that for a task like this, you’ll use CSS files that incorporate many more semantical styles than just the usual header, paragraph, strong, emphasis etc.</p>
    <p>The only way I can see to adequately deal with this would be a sidebar or inspector window that visually lists all styles available in the active CSS file (it would also be helpful to use more than just one CSS file per document!). This sidebar or inspector window would also be the place where you could assign shortcuts to each of these styles.</p>
    <p>Fortunately, this doesn’t only apply to the very specific task of writing Xcode documents, but to all kinds of texts that are, so to say, “semantically ambitious”. ;–)</p>
    <p>So I feel this would generally be a very useful addition to TypeMetal.</p>
    <p>Uli

    #1207

    Reply


    Uli Zappe

    Oooops – where do these visible paragraph marks in my last post come from?

    Uli

    #1208

    Reply


    Troy Stephens

    Hi Uli!

    Thanks so much for coming back to report on your results!

    Have you tried creating and using a snippet set, to make applying semantic styles quicker and easier? It’s not quite as automatic as inferring suggested class and id names from an associated CSS file would be (a potentially nice future enhancement), but it does help you to be more systematic about which classes go with which kinds of elements, and even enables creating more complex, multi-element constructs with a single operation. The purpose of snippet sets is to enable more “semantically ambitious” HTML :-) so please do let me know of any shortcomings or challenges you run into in attempting to use them for efficient writing!

    Thanks,
    Troy

    (ps – Sorry, those HTML tags appear to be the result of a bbPress+MathCaptcha bug. When MathCaptcha prompts you to “try again” when submitting a post, it plops the post body complete with HTML tags into the text area, and those tags then get escaped on the second submit. Looks like maybe I need to look into fixing this myself, as surprisingly no one else has yet. :-)

    #1213

    Reply


    Uli Zappe

    Hi Troy,

    no, I haven’t tried the snippets yet, mostly for two reasons:

    1. Time constraints and priorities
    You might be well aware how much software engineers love to document their code. ;-) I’m more thorough here than most others I know, and even I just don’t feel inclined to put up with the additional work to transfer the possibly complex content of several CSS files into snippets. So I’d rather go on coding instead … :-)

    2. WYSIWIG
    A sidebar as I envision it could and ideally would be (kind of) WYSIWIG as far as font, font sizes, font and background colors etc. of a CSS style are concerned. At least for a very visual person like me, that would be an immense help in quickly selecting the appropriate style. It just “feels” like working with a word processor should feel.

    Since both points are not really limited to developers, I think adding such a sidebar would be a big step towards making TypeMetal a full-fledged “HTML word processor”. In fact, many less technically inclined people might only this way become aware of the powers of CSS.

    > Sorry, those HTML tags appear to be the result of a bbPress+MathCaptcha bug.

    Ah, so I’ll try to play a trick on them by writing this in TextEdit, updating the Captcha, and only then copying the text into the text field and immediately sending it – let’s see if this works …

    #1214

    Reply


    Uli Zappe

    Hi Troy,

    I just downloaded the “Online Help” sample snippet set to try it, but this doesn’t seem to work (most snippets have a red mark in the snippets pop-up dialog) because – I suppose – the corresponding CCS file isn’t specified. Could you point me to the correct CSS file path that works with your example snippets? Thanks!

    Uli

    #1215

    Reply


    Troy Stephens

    Hi Uli,

    You should be able to use this, or any snippet set, independent of any particular CSS file. (It’s perfectly valid to annotate HTML with “class” names that aren’t mentioned in the associated CSS.)

    Certain snippets will be disallowed in the completion list based on the current insertion point or selection: If inserting, or wrapping the selection in, the snippet would produce invalid HTML, TypeMetal shows a red light for the snippet in the completion list. Almost always, the snippet’s [top-level] element is the reason for this — e.g. you can’t insert a <section>, <div>, or other block-level element inside a paragraph. You need to first exit to block level ([Esc] and [Tab] can be helpful for this).

    There is also, separately, standalone validation of snippets in the snippet editor, based on the specified document type (e.g. HTML 5). But it doesn’t sound like that’s what you’re talking about here.

    Are you able to make things work by first ensuring you have a valid insertion point or selection for the desired snippet?

    Troy

    #1216

    Reply


    Troy Stephens

    and in belated answer to your earlier post:

    I understand completely regarding time constraints and priorities! I also share your desire for better ways of documenting code, which was a big driver for me in developing TypeMetal! I hope to be able to pursue that particular use case further in the future. Snippet sets do take a little bit of time investment, and it would be nice indeed to make the process of identifying CSS styling usage patterns more automatic. (The ability to survey usage patterns across an entire “project” would help facilitate this.) On the upside, I put in provisions to help with building a snippet set “as you go along”, so you don’t have to feel like it’s a daunting task you have to complete up front, before you can get to the writing that’s your actual goal. Simply create a new, empty snippet set, save it somewhere, associate it with the HTML file you have open, and keep both the HTML document window and the snippet set window open side by side. As you find the need for a new snippet (let’s say you want to wrap some text in “<code class=”objc-class-name”>”), you can either:

    (1) Click “+ Snippet” in the snippet set window to add the new snippet (typing “code.objc-class-name” for the snippet’s shorthand, and a brief descriptive name like “Objective-C Class Name” for its title, is all you need). The new addition is instantly indexed by TypeMetal, so you can now go back to your document and Ctrl+/ to complete the snippet by typing something short like “ocn”.

    or

    (2) Create the first example manually in your HTML file, then tell TypeMetal to create a new snippet from it: Wrap some text in a “code” element (Cmd+Shift+C is a handy shortcut for “code”), then Cmd+L to edit its attribute list and add a “class” attribute with value “objc-class-name”. Now you can right-click the “code” element in the DOM path bar, and choose “New Simple Snippet: code.objc-class-name”. TypeMetal adds the new snippet to your document’s associated snippet set (you may want to give the snippet a descriptive name). And from now on, you can insert or wrap in a “<code class=”objc-class-name”>” element by invoking that snippet.

    In this way, you can build up a useful snippet set as you go along, rather than having to do it all at once. I do like your suggestions about more automatic ways of suggesting CSS classes to apply, though — definitely worth considering for the future!

    Thanks, and let me know if this does/doesn’t help! Also, if you want to send me an example HTML+CSS file set for what you’re working on (you can email it to me at “support”), I’d be happy to draft a snippet set for you to try getting started with.

    I’d love to help you get to where you can give TypeMetal a real try for your technical writing. Your experience with doing so would be of great interest!

    Thanks,
    Troy

    • This reply was modified 2 years, 1 month ago by  Troy Stephens.
    • This reply was modified 2 years, 1 month ago by  Troy Stephens.
    • This reply was modified 2 years, 1 month ago by  Troy Stephens.
    • This reply was modified 2 years, 1 month ago by  Troy Stephens.

    #1222

    Reply


    Uli Zappe

    Hi Troy,

    thanks for the reply!

    Currently, I’m not yet ready for documentation in earnest in my project, so I cannot send you any files yet. I’m just tinkering around with TypeMetal in preparation for things to come …

    You were right with the insertion point preventing the snippet from being applied.

    However, once it worked at all, things seemed a bit unstable for me. I tried to apply the section.tip snippet. I once succeeded when I put the cursor before the first line of text in my document (luckily there was this empty first line by chance). But that also meant I could only activate the snippet first and then start typing. I found no way to make an already typed piece of text a section.tip.

    However, after this successful first trial I could not repeat this process. I tried to use an empty line at the end of my test document, but strangely, from then on, the Ctrl-/ shortcut (an unfortunate shortcut in German as ‘/’ is Shift-7 on a German keyboard …) did not work anymore as it did before. Either nothing happened at all, or a blue oval with an ‘*’ in its middle appeared at the insertion point. But no matter where the insertion point was or whether I selected text or not, I could not make the snippet list appear again. Restarting TypeMetal fixed this.

    BTW, Cmd-Ctrl-/ (New Simple Snippet From Selection) does not work at all in German (where it’s actually Cmd-Ctrl-Shift-7), as this shortcut brings up the Help menu in any OS X application. Yes, I know I can overwrite shortcuts in System Preferences, but this is unstable (gets lost from time to time) and cumbersome, so I have not bothered yet.)

Viewing 12 posts - 1 through 12 (of 12 total)

Reply To: TypeMetal for Xcode docsets?
Your information:





28 − 25 =