[Known issue] Links in PDF manual don't link to what they should

[Dragon1-1]

The PDF manual appears to be trying to open some kind of HTML files instead, which are nowhere to be found:
file:///home/runner/work/f-4e-manual/f-4e-manual/book/html/intro/introduction.html
It seems instead of linking to different parts of the PDF, it links to HTML files used to create it, or it would, if I was on the creator's PC. I'm not, so the links go nowhere. They should link to other pages of the PDF manual instead.

Also, the table of contents and page numbers of the PDF manual could use improvement. Right now, between the link issue and the fact TOC only has section numbers and not page numbers (and inline references use section-subsection-page format not present anywhere...), the only way to find something is CTRL-F. The PDF is not unusable, but it's definitely not up to par even with the F-14. It might be easier to update a webpage, but for the users, it's easier to read a PDF.

Edited April 6 by Dragon1-1
Edited because I realized the links did not go to website

[Zabuzard]

Hey there, those are known issues and already reported here:

https://github.com/Heatblur-Simulations/f-4e-manual/issues

Cheers

[TheBiggerBass]

vor 3 Stunden schrieb Zabuzard:

Hey there, those are known issues and already reported here:

https://github.com/Heatblur-Simulations/f-4e-manual/issues

Cheers

But don't seemed to be solved yet.

[Zabuzard]

Correct. You can read on why in the link.

That said, the manual is a community effort. So if you are feeling fancy, feel free to investigate into fixing it. As explained in the link, this needs to be solved in the Chrome API, not on our side

Edited April 7 by Zabuzard

[Dragon1-1]

What does the Chrome API have to do with a PDF document? Can't you just do this the old fashioned way, instead of faffing about with Chrome? I've made nice looking documents in Microsoft Word (admittedly, without hyperlinks, but with tables), and every other module has a manual with tables that are not cut off and internal links that work. The real problem seems to be that you wanted to be really fancy with the documentation, and ended up with a lot of extra bugs for no added value.

Looking at Github, you built a whole project, with IDEs, elaborate hierarchy, a Github repo for that matter, all for an... instruction manual. While I'm aware writing docs is a big job, and it is useful to organize it in some manner, I think at least some of the dev time that went into this Rube Goldberg contraption could have been spent elsewhere. Especially since looking at how the document is structured, its formatting looks less complex than that of the original 70s era Dash-1 (which, admittedly, features some fancy things that work well in print but are a PITA on a computer). I'm not especially fond of Google Docs, but if you want to make this a collaborative project, that looks like a more appropriate tool. 1000 pages seem like a lot until you realize the formatting gives it only about 30 lines of text per page, and that's without pictures.

Edited April 7 by Dragon1-1

[Zabuzard]

For various reasons the team decided to go with a website instead of a PDF as main format. This has multiple advantages and for example also enables embedding it ingame with the "explain me"-feature and also other more sophisticated features such as embedding Youtube videos or making clickable cockpit navigation inside the manual.

These things are not possible in a classic PDF. So its a website, first and foremost.

The website version also has the big advantage that it can be updated instantously detached from the DCS update cycle, its accessible on all devices, also offering optimized versions for mobile phones and tablet devices. Markdown as format is a good fit since it allows non-tech people to contribute as well, which is important since this manual is a community project - not just maintained by the devs.

In contrast to the F-14, whose setup doesnt allow any PDF export to begin with, the team thought it would be nice to be able to also offer a PDF as second class citizen. So the approach via Chromes print-API was choosen to enable a working and usable PDF export at low maintenance cost.

Its important to understand that the PDF is not the main format for this manual and that the alternative would be no PDF at all. You are most welcome to suggest and find a better alternative that works with the existing mdbook format.

[Zabuzard]

3 hours ago, Dragon1-1 said:

and ended up with a lot of extra bugs for no added value.

I suppose this is where opinions differ then.

The team is convinced that the website-approach enables a lot of useful features that, based on user feedback, seems to be highly appreciated by most users.

[Dragon1-1]

The way I see it, the F-14 manual format is much superior. For one, it has more than 30 lines of text per page. The F-4 one looks like it was made to be read on mobile. I suppose it could be useful for those who use knee-mounted tablets, but for me, it just makes it annoying to read. Even the actual dash-1 is better on that account. The website isn't great, either. Let's just say that it takes about a third of my screen space... the left third. On very wide screens, there are ergonomic arguments for leaving big margins on the sides (like this forum does). For that configuration, there are none.

The fundamental problem with the website, though, is that it's heavy. All those fancy "user-friendly" features pull away performance on an already heavyweight module. Vintage radars that show ground returns are expensive in DCS, and the Phantom really doesn't need another resource hog, especially given its detailed systems simulation. While I suppose the whole HBUI idea was needed for Jester and bombing calculator anyway, there's a reason why in gaming, such things are usually written in C++. Somehow, PDFs are perfectly adequate for the glass cockpit jets, and yet here we ended up with an in-sim web browser seemingly for the sole purpose of explaining a pretty straightforward steam gauge jet from the 70s. Maybe some people like it, but to me, it seems that the sheer complexity of the system and its performance demands are disproportionate to the gains it provides. Usually, the point at which you say "what this thing needs is an integrated web browser" tends to be the point at which feature creep had well and truly gotten out of hand.

1 hour ago, Zabuzard said:

You are most welcome to suggest and find a better alternative that works with the existing mdbook format.

How about exporting to a format that allows you to do basic postprocessing, and then exporting to PDF? It's fairly obvious that the current solution has issues, and they are caused by the automated PDF converter being dumb. The obvious solution is, use the dumb converter to generate something that's close enough, and then fix the things it can't do by hand, or even by a script that would, for instance, fix the chapter links and add page numbers in a section-subsection-page format. Yes, it's more work, but that could be the only way to fix the issues.

One more thing. To me, it seems that the technical part of the Phantom is very complete, with only a few missing features. The manual has massive sections on mission planning, training missions, modding, liveries, etc., which are of no concern to a pilot trying to find an AAR checklist before he burns his last 700lbs of gas. The vast majority of the part of the manual most useful in flight will not change. So why not put that part into a nifty, F-14 style PDF manual, spend a few hours formatting it right, and leave it alone until something is actually added to the jet itself that merits modifying it. Sure, it's more work, but it's not going to happen often, and always come with a DCS update, anyway. The remainder, no doubt subject to many more changes, corrections and updates than the "what does this button do" part, might stay on the website for all I care, since I'm unlikely to be reading a livery making tutorial mid-flight. 

[TheBiggerBass]

Choosing another format than .pdf for the manual is fine for me. But there should be a downloadable version which does not require an online connection to be functional.

[Dragon1-1]

Just to specify, I didn't mean not using PDF as a final product, I meant not compiling directly to PDF, so manual adjustments (or scripted ones) can be done before creating the (effectively uneditable) PDF. The intermediate format can be whatever this website export crock can handle with the fewest issues.

Now that I think of it, I'd like to disable the external site loading altogether. It seems like there's no place where it's explained what tech this in-sim browser is based on (Chromium, probably? Would explain the performance issues...), what has been done to make it secure, or what privacy controls are there. If it can load YouTube videos, it can load a whole lot of things, some of which I might not want loaded. Another reason to ask for a proper offline PDF manual.

Edited April 8 by Dragon1-1

[Zabuzard]

5 hours ago, TheBiggerBass said:

Choosing another format than .pdf for the manual is fine for me. But there should be a downloadable version which does not require an online connection to be functional.

In case you have missed it, unlike for the Tomcat, the Phantom does come with a PDF. The PDF is auto-generated out of the website version. This thread is about some people not liking that this PDF is essentially a second class product and not first class, such as the website (and hence has some smaller issues such as broken links).

4 hours ago, Dragon1-1 said:

Just to specify, I didn't mean not using PDF as a final product, I meant not compiling directly to PDF, so manual adjustments (or scripted ones) can be done before creating the (effectively uneditable) PDF

The intermediate product is markdown. If you find proper tools to make PDFs out of markdown, go ahead. I want to emphasize again that the manual is fully open source and a community project. So if you (or anyone else) has some extra time you can spend it on implementing a better PDF. For various reasons (some layed out earlier), the team wont spend too much time on an improved PDF version.

4 hours ago, Dragon1-1 said:

Now that I think of it, I'd like to disable the external site loading altogether.

Feel free, select "Offline" in the Special Options and no internet traffic will happen from our side at all.

The in-game manual is not an online manual, its an offline-website being displayed by the browser (located in DCS/Mods/aircraft/F-4E/UI/Manual).

4 hours ago, Dragon1-1 said:

what tech this in-sim browser is based on

CEF (Chromium Embedded Framework).

4 hours ago, Dragon1-1 said:

Would explain the performance issues...)

It does not impact performance. If you remove CEF entirely you will maybe gain 1 FPS in total only. Heatblur has of course tested this before adding the technology. If you select "Lower HB UI Refresh Rate" even that (small) impact will be gone entirely: https://f4.manuals.heatblur.se/dcs/special_options.html#lower-hb-ui-refresh-rate

4 hours ago, Dragon1-1 said:

or what privacy controls are there

You can fully control which domains it can talk to and which not. See the manual for details: https://f4.manuals.heatblur.se/dcs/special_options.html#domain-access

4 hours ago, Dragon1-1 said:

Another reason to ask for a proper offline PDF manual.

The PDF is available at GitHub for download and in your local folder DCS/Mods/aircraft/F-4E/Documents.

Edited April 8 by Zabuzard

[Dragon1-1]

3 hours ago, Zabuzard said:

In case you have missed it, unlike for the Tomcat, the Phantom does come with a PDF.

Wait, are you trying to say the Tomcat doesn't have a PDF manual? Because I'm pretty sure there's a rather nice one in the Tomcat's docs folder.

In fact, what I'm asking for is for the Phantom manual be brought up to the standard of usability of the Tomcat one. All it has right now is a bad website and a PDF that's also bad, in other ways. 

3 hours ago, Zabuzard said:

The intermediate product is markdown. If you find proper tools to make PDFs out of markdown, go ahead.

I meant something like pulling the markdown into MS Word and manually adjusting the tables. The second step is kind of important, too. No, you likely won't be able to just hit "compile" in Github and get a perfect result. I really don't like the idea of foisting this job on the community, either. Sure, I could copypaste text and pics from your website into Word, apply some formatting to get it to look better than the current PDF, and then send you the results. But why should I have to do it?

Right now, I feel like I might as well use the original -1 and -34, and hope that, since you're much better at making planes than at document and website design, nothing significant will be amiss. Just wish you stuck to what worked in Tomcat and Viggen, rather than give us this dolled up mess nobody actually asked for.

I ran out of SP content for the Phantom (content that works, anyway), but if there's no progress by the time it accumulates enough new stuff for me to get back to it, I might spend an afternoon or two copypasting things. I still think it's a step down, considering I didn't have to do it for other modules.

 

[Zabuzard]

30 minutes ago, Dragon1-1 said:

Wait, are you trying to say the Tomcat doesn't have a PDF manual? Because I'm pretty sure there's a rather nice one in the Tomcat's docs folder.

The Tomcat PDF version was manually created, it is not connected to the website content. Its not maintainable and consequently lacks behind the true content for many many "versions" already. Or in simple terms: It may look nice but its bad.

30 minutes ago, Dragon1-1 said:

All it has right now is a bad website

In that we have a fundamental disagreement, I suppose.

30 minutes ago, Dragon1-1 said:

But why should I have to do it?

You dont have to, that is a misunderstanding. I am saying you (or anyone else) can contribute if they want - helping out when Heatblur simply has no time to take care of it right now (which is the case for the PDF topic).

30 minutes ago, Dragon1-1 said:

what worked in Tomcat and Viggen

It doesnt, thats the thing. The Viggen manual is a failure from a dev-side, its unmaintainable. So much in fact that the topic was taken over by a dedicated community member (who is now actually part of the team).

The Tomcat manual was an improvement over that, it can be edited and deployed by the team much easier (and also detached from DCS update cycles). But therefore it essentially sacrified the PDF completely. And unfortunately didnt really make a lot of use of the benefits of being an interactive website, so it was hard to see why the website-version is superior.

The Phantom manual learned of all these things, its easy to edit by the entire team (even including the community) and a format was chosen that at least allows a PDF export. Automatic deployment is an enourmous help, allowing anyone to make a quick edit with instant deployment and not waiting for months until the dev with the arcane knowledge and a working local setup shows up. Unlike the Tomcat manual it starts to explore the advantages of it being a dynamic website, for example by having embedded videos, a great search function, themes, mobile support, tablet support, being able to share direct anchored links to certain topics in chat when helping people, in-game embedded manual with "explain me" functionality. And more ideas that come to mind, such as clickable cockpit overview pictures or showing "where is this" cockpit overview pictures on the side as you read the content of a specific system.
There are a lot of things and consequences that you, as customer, dont see when it comes to these things. For example the Phantom manual being so complete and content-rich is a direct consequence of the format we choose - allowing everyone to contribute without much friction, instead of only having one or two editors who write the entire document and lack expert knowledge on certain topics.

I understand the desire for a nice PDF, no one from the team is disagreeing on that. But dont forget that there are so many more use cases. There are so many people who read through the manual on their phone from bed, people who have the manual on their tablet while flying. Plenty of people using the "explain me" feature. Or simply checking out the manual from their desktop PC. The PDF is great for offline usage, especially during travel. And thats why it was important for us to at least offer a PDF export. Its shortcomings are very unfortunate, but it is definitely better than no PDF at all - and to be fair, they arent a dealbreaker either. The PDF version still works just fine for studying the aircraft, its just less convenient.

Also worth noticing that Chucks Guide will eventually drop as well, offering a great PDF experience - which the team can then embed right into the game as well and also ship it as "official" document.

Either case, I do not feel like this discussion is moving forward much. And it also seems to drift away from the threads topic. To make it clear again: Currently Heatblur is not able or planning to invest time into improving the PDF version. Please use the website version if possible (online or offline) or accept the shortcomings of the PDF version for the time being.
The community is most welcome to help out on this front (see GitHub link)

Hope that answers your questions, cheers

Edited April 8 by Zabuzard

[Dragon1-1]

30 minutes ago, Zabuzard said:

The Tomcat PDF version was manually created, it is not connected to the website content. Its not maintainable and consequently lacks behind the true content for many many "versions" already. Or in simple terms: It may look nice but its bad.

Let me see, it has all the switchology, it has LANTIRN, it has the checklists, it explains everything in a concise, easy to read way. In what way is that bad? That it doesn't have all the random modding information or pointers for skinners (what you call "content-rich")? In my eyes, that's a plus. It's very professionally done, too, with all the navigation features I'd have expected from it. The only unneeded thing is the history lesson at the beginning, but that's just a DCS tradition at this point.

The point is, you seem to think the website sync, and things you add to the website, including the ability to update off-cycle, are of more value than they actually are. Most of the extra content you added is actually pretty useless for me, as are the "interactive features". What you have actually done seems to have opened the door to endless feature creep of what should have been a simple document to be referenced by the pilot and RIO, during flight ops or in preparation for them. 

I'm not asking for an "All Things Phantom Wiki". I'm asking for a flight manual. You seem to be confusing the two. Keep your website, by all means, I won't be using it, but modders might. I'm only asking, do spend some time on manually building a flight manual, too. Same thing as for the Tomcat, 100% usable, zero bloat, and it's got a nice table of contents on the side. It doesn't need to super-maintainable, just keep the sources around in case you actually add something that's worth looking up mid-flight.

The whole point of this discussion is to convince you to make an effort to provide a concise PDF document that is an in-flight reference and nothing else. The Tomcat PDF manual is exactly that. Instead of pretending it doesn't exist, take a good, hard look at what it is actually used for, and you'll see it's perfect for that single purpose. There's a reason Tomcat NATOPS doesn't include information on how to change tyres on the landing gear. 

[Zabuzard]

I feel like there is nothing I can add to the discussion anymore really.

Thank you for your input

Edited April 8 by Zabuzard

[Rudel_chw]

5 minutes ago, Zabuzard said:

I feel like there is nothing I can add to the discussion anymore really.

Thank you for your input

what an elegant answer, now I remember there is a reason why I have this person on ignore  

[Dragon1-1]

22 hours ago, Zabuzard said:

I feel like there is nothing I can add to the discussion anymore really.

That's because you're focused trying to convince me the current approach is better, and seem to have already resolved not to fix the problems with the PDF version. If you're not willing to consider whether your design philosophy has downsides that negatively impact customer experience, there's indeed no point in this discussion.

At this point, I might be better off asking Chuckowl whether he's willing to entertain making a more in-depth guide for this module than for the others.

22 hours ago, Rudel_chw said:

what an elegant answer, now I remember there is a reason why I have this person on ignore  

And I'm glad you're never going to be involved in making anything worth paying for.

Edited April 9 by Dragon1-1

[Q3ark]

On 4/8/2025 at 12:55 PM, Rudel_chw said:

what an elegant answer, now I remember there is a reason why I have this person on ignore  

This is the answer

[Dragon1-1]

Too bad I came here looking for a solution, then.