Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Already on GitHub? Sign in to your account

TOC headings not created in latest version of XCode. #409

Open
ExoticObjects opened this Issue Oct 18, 2013 · 28 comments

Comments

Projects
None yet
6 participants

(Programming Guides, Class References, Category References, and Protocol References) used to be displayed in TOC in XCode 4.5 and greater. But they are not displayed in XCode 5.0.1.

Dash displays Classes, Protocols, Categories, Methods, Properties, Types and Constants.

Collaborator

robvdveer commented Oct 19, 2013

Could you add screenshots of the differences? Please note that xcode 5.0.1 is making up its own quickhelp, perhaps you are seeing that.


http://simplicate.weebly.com

On Sat, Oct 19, 2013 at 12:39 AM, Exotic Objects notifications@github.com
wrote:

"Programming Guides," "Class References," "Category References," and "Protocol References" used to be displayed in TOC in XCode 4.5 and greater. But it is not displayed in XCode 5.0.1.

Dash displays "Classes", "Protocols", "Categories", "Methods", "Properties", "Types" and "Constants."

Reply to this email directly or view it on GitHub:
#409

Unfortunately I can only make a screenshot of this issue NOT working. To show it working I'd need to download XCode 4.6 again. XCode 5 has no documentation browser.

At any rate, here's what the left menu looks like in the documentation browser in XCode 5.0.1:

screen shot 2013-10-19 at 1 40 07 pm

Note that the XCode 5 doc set has menu items that can be selected, but Jalapeno Documentation does not. It used to! (Programming Guides, Class References, Category References, and Protocol References)

Also, I used to be able to add my own user guide that would appear in the menu by creating and including a template.markdown file, like so

--include "${PROJECT_DIR}/Documentation/appledoc/Using Jalapeno-template.markdown" \

That also has stopped working.

Thanks!

Owner

tomaz commented Oct 19, 2013

This might be linked to #409

Erm, unless I'm missing something, this IS issue #409 :-)

Owner

tomaz commented Oct 20, 2013

Haha, my bad, meant #408...

I've read through enough of the issues here to understand that we probably shouldn't hope for a quick fix to this. I don't have time to work on appledoc. But people have done so in the past... @robvdveer, for example, has done great work on issues dating all the way back to #2!

The argument I'm trying to make is this: a lot of people use appledoc. Currently, the latest version is unusable with the latest version of xcode. Docset won't display at all. Roll back a few versions and you can get a version that will install a docset, but no table of contents (TOC). This means that navigation is harder, of course, but it also means that some content is completely inaccessible - comments on enums, for example. Doesn't that inconvenience a lot of people? Dunno...

I wish I could allocate the resources, and might have to figure out how to. But at any rate, I just wanted to raise an alert that, as issues #408, #409 and #412 seem to confirm, the current thing is busted. Hopefully those who have fixed it and extended it in the past might find some time to have a look...

Contributor

boredzo commented Oct 30, 2013

I'm working on a presentation I'm giving in a week, but I'll take a break at some point to look into all three issues.

Collaborator

robvdveer commented Oct 30, 2013

If i weren't crippled by bad health, i'd fixed them all by now. Thank you for the compliments, don't forget all the work tomaz and the community put in.


http://simplicate.weebly.com

On Wed, Oct 30, 2013 at 8:25 PM, Peter Hosey notifications@github.com
wrote:

I'm working on a presentation I'm giving in a week, but I'll take a break at some point to look into all three issues.

Reply to this email directly or view it on GitHub:
#409 (comment)

Feel better @robvdveer...

Thanks @boredzo!

And of course, thanks to @tomaz! appledoc is awesome. Just needs a little nudge...

Owner

tomaz commented Oct 30, 2013

Agree. Traveling this week, so can't do much about it. Will take a look once I return.

Sent from my iPhone

On 30. okt. 2013, at 20:23, Exotic Objects notifications@github.com wrote:

I've read through enough of the issues here to understand that we probably shouldn't hope for a quick fix to this. I don't have time to work on appledoc. But people have done so in the past... @robvdveer, for example, has done great work on issues dating all the way back to #2!

The argument I'm trying to make is this: a lot of people use appledoc. Currently, the latest version is unusable with the latest version of xcode. Docset won't display at all. Roll back a few versions and you can get a version that will install a docset, but no table of contents (TOC). This means that navigation is harder, of course, but it also means that some content is completely inaccessible - comments on enums, for example. Doesn't that inconvenience a lot of people? Dunno...

I wish I could allocate the resources, and might have to figure out how to. But at any rate, I just wanted to raise an alert that, as issues #408, #409 and #412 seem to confirm, the current thing is busted. Hopefully those who have fixed it and extended it in the past might find some time to have a look...


Reply to this email directly or view it on GitHub.

tomaz added a commit that referenced this issue Oct 31, 2013

Fixed docset installation. Addressing #407, #408, #409 and #412.
The problem was due to template files copy step issued for each output generator. This code basically deletes output path and copies template files over. However in doing so after docset was already prepared, it invalidated all previous effort.

PS Don't worry about the number of addressed issues - these are (likely) pointing to the same problem!
Owner

tomaz commented Oct 31, 2013

I think I found the culprit, please verify and close the issue if so.

To keep merit where it belongs :) - it's not @boredzo code fault, the change he introduced merely exposed the weakness of generation system.

tomaz added a commit that referenced this issue Nov 2, 2013

Fixed docset publish default values case. Addressing #409 and #412.
This commit makes docsetutil tool compile the xar file, however I did not test the results. Plus the code may potentially introduce Dash compatibility issues added with commit 75a3907.

@tomaz, unfortunately I don't understand your comment from #408. I'm commenting here as that issue is closed.

The error is from docsetutil. I tried it myself and I can reproduce the error (if failing to provide cmd line switches for docset that seem to be fine in your script). With this new fix it works. Give it a go and comment on #409 (closing this issue to keep focus - it's referenced on #409 anyway).

You were able to reproduce #409 by failing to provide cmd line switches? If so, which switches? As you say, they seem to be fine in my script (see #408). If my script is fine, what can I do differently? Using latest build and still no left side nav in docset...

Owner

tomaz commented Nov 2, 2013

Internally appledoc uses docsetutil to prepare xar file; docsetutil requires a bunch of parameters, -download-url (which corresponds to --docset-package-url) among others. Latest commit fixes default case - when not providing custom docset package url. In such case appledoc falls down to default value which prevents docsetutil error.

I was more or less fixing #412 hoping it would also "automagically" fix this issue :) Will take another look as soon as I can.

So, am I the only one having this issue? Can we confirm that it's a bug? If it's an anomaly of my script or setup, I'd be happy to know that...

Collaborator

robvdveer commented Nov 9, 2013

Do you have the latest document templates installed? If. Unsure, delete the templates folder. I'm not sure of the location, i believe ~/.appledoc


http://simplicate.weebly.com

On Sat, Nov 9, 2013 at 6:00 PM, Exotic Objects notifications@github.com
wrote:

So, am I the only one having this issue? Can we confirm that it's a bug? If it's an anomaly of my script or setup, I'd be happy to know that...

Reply to this email directly or view it on GitHub:
#409 (comment)

I deleted the templates directory (which is ~/.appledoc, as you said), reinstalled appledoc with

sudo ./install-appledoc.sh -t default

still no deal...

Collaborator

robvdveer commented Nov 9, 2013

Ok sorry it didn't work. At least we can rule this out...


http://simplicate.weebly.com

On Sat, Nov 9, 2013 at 6:23 PM, Exotic Objects notifications@github.com
wrote:

I deleted the templates directory (which is ~/.appledoc, as you said), reinstalled appledoc with

sudo ./install-appledoc.sh -t default

still no deal...

Reply to this email directly or view it on GitHub:
#409 (comment)

Owner

tomaz commented Nov 9, 2013

It's a bug it happens to me too. My bet is there was a change in how Xcode5 handles docsets - docset guide is now marked as legacy, but I couldn't find any new documentation on subject.

So, can we help you try to find documentation? Maybe send a note to Tim Cook?

Owner

tomaz commented Nov 17, 2013

bugreport.apple.com should be better first step :)

I think that might take too long...

FWIW, I believe Doxygen is borked in XCode 5 as well. My Box2D, Chipmunk and various other docsets don't work - can only open folders, can't open files. I mention this because maybe you've corresponded with the Doxygen guy in the past? (I've seen Stackoverflow threads where the two of you chimed in...) Presumably, he's trying to figure it out as well. There aren't a lot of people who've made document readers like this... 😉

Owner

tomaz commented Nov 18, 2013

:) It may take long, but would at least get signal to Apple that we need this. I still didn't get to check how Apple's own docsets are implemented in Xcode 5. So far they used tokens.xml file(s) to describe TOC structure. They may have changed the format, or use completely different method for describing it.

FWIW, Doxygen is fixed in latest XCode preview.

Ok, on one level I think it's kind of pointless to report a bug to Apple. It will probably take a year before it's addressed. When I finally did resign myself to the idea, it occurred to me that it would make a lot more sense for you (@tomaz) to report the bug. As someone who's written a document reader, you'll be able to inform the report with a lot more detail that will be useful to them. All I can say is 'the table of contents doesn't show up.'

So any chance of getting this fixed? As it stands, I can't use appledoc, as documentation without a table of contents gives the impression of being 'broken', which nobody wants... I'm guessing I'm not the only one.

The last commit here says "This commit makes docsetutil tool compile the xar file, however I did not test the results."

Really? I can't imagine committing code without testing if it works.

Owner

tomaz commented Dec 22, 2013

No point in being condemning :) I do my best, but was simply too occupied in the past year to make anything substantial. I am connecting with other developers though, so hopefully next year there will bring better progress.

As to my commit message: I was referring to #412; I implemented docset publishing upon user request. Appledoc only generates xar and atom files, but doesn't handle upload. I also don't test publishing and subsequent integration with Xcode, it's just too much time and variables here to be able to support and cover them. But I do test that files are created and that they look fine. This is what my comment was about, it wasn`t the best choice of words though :)

If I can be a bit sarcastic: appledoc is open source, and as such anyone can step in and address things. Not pointing fingers to anyone, there were sure tons of great folks contributing to the project and it definitely wouldn't be where it is now without their help!

I misinterpreted your comment, but as you note, it was open for misinterpretation! Sorry - I also could have chosen my words better...

Here's what I'm trying to say. I could spend 1-4 weeks spinning up on appledoc. From what I've seen, it appears to be really well written, but it's undeniably complex. I might get lucky and fix the problem quickly, but most likely would not. It's irrelevant, unfortunately, as there's no way I can spare that time... So, while it's true that appledoc is open source and anyone can step in and address things, most people are in my position - too busy to even consider it.

Where does that leave appledoc? Well, maybe it doesn't bother anyone else that the left menu navigation is broken... In which case, lots of people will continue to use it. But for me, this is a deal-breaker. Or, maybe Apple is finally going to properly implement documentation - it's pathetic that they never really have - in which case people will switch to whatever that is. Or, maybe people will be happy with Doxygen - but I already know that we all like appledoc better :-) Whatever the case, I don't see Apple thinking that their failure to publish changes to the way XCode handles docsets is a 'bug.' It seems extremely unlikely that they'll remedy this situation anytime soon.

So someone has to dive in - it seems a shame for the thing to stay broken. I'm hoping you can find some time @tomaz, or perhaps some of the other committers can step in. It's a great piece of work. Thanks for creating it in the first place! I hope it can get over this bump...

@tomaz tomaz added this to the 3.0 milestone May 16, 2014

@tomaz tomaz added the Known label May 16, 2014

What is this issue's status? Any recent developments that would address this?

The same issue here, isn't it related to some temp/cache files? I was able to create a proper docset but I think after I deleted stuff in ~/Library/Developer/Shared/Documentation/DocSets it seem to break

irshadpc added a commit to irshadpc/appledoc that referenced this issue Mar 6, 2017

Fixed docset installation. Addressing #407, #408, #409 and #412.
The problem was due to template files copy step issued for each output generator. This code basically deletes output path and copies template files over. However in doing so after docset was already prepared, it invalidated all previous effort.

PS Don't worry about the number of addressed issues - these are (likely) pointing to the same problem!

irshadpc added a commit to irshadpc/appledoc that referenced this issue Mar 6, 2017

irshadpc added a commit to irshadpc/appledoc that referenced this issue Mar 6, 2017

Fixed docset publish default values case. Addressing #409 and #412.
This commit makes docsetutil tool compile the xar file, however I did not test the results. Plus the code may potentially introduce Dash compatibility issues added with commit 75a3907.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment