On 10 October 2015 at 13:29, Felix Schumacher <[email protected]> wrote: > Am 10.10.2015 um 14:18 schrieb sebb: >> >> The printable docs serve several purposes: >> >> - help pages for use in JMeter itself. >> [It only uses component_reference.html and functions.html.] >> The display uses the built-in Swing components, and only supports >> links within the current page. >> I think that is an advantage, as the user cannot get lost, and there >> is no chance that the code will have to cope with arbitrary HTML. >> It is important that only the relevant information is displayed, so >> unnecessary items such as side menus should not be present. > > Right. I think it useful too, that the user can't get lost. And since the > user should not leave the page, the menu is not useful there. > >> >> - offline browsing of all the JMeter user documentation. >> The side menus are not useful in this case. >> The links to online resources won't work, and the internal links from >> the side menu are made available from the main page. >> Having no side menu leaves more room for useful content. > > Screens get really wide today, so a menu at the side might be helpful in > such a case, but generally I think you are right, that not all resources > should be linked in the offline pages.
A wide screen means I can have the doc side by side with JMeter, plus some other info. The menu just wastes space. Besides, screens are also getting smaller (notepad etc). >> >> - printing manual pages. >> The side menu is not useful here; it just wastes paper. Likewise the >> online only bits of the title banner. >> It should be possible to download the JMeter release and have >> everything needed to use it offline. > > If you look at the printed pages (in firefox there is a print preview), you > will see, that there are no banners, menus and even no footer (while I think > the footer could be useful). Yes, with trunk the generated pages have much better printable representations. However that does not help with offline usage. > Are there any points you know, that a online connection is needed for the > online docs? (The fonts should fall back to local ones) Links to online resources obviously don't work. >> >> >> It would be useful to be able to print pages direct from the internet >> without the menus, but that is a separate issue. > > That is possible right now with current trunk. Might be nice to add this to the current online docs if it is easy to do (e.g. just CSS changes). > Regards, > Felix > >> >> >> On 10 October 2015 at 12:41, Felix Schumacher >> <[email protected]> wrote: >>> >>> Am 06.10.2015 um 10:36 schrieb sebb: >>>> >>>> On 5 October 2015 at 21:12, Felix Schumacher >>>> <[email protected]> wrote: >>>>> >>>>> Am 05.10.2015 um 17:18 schrieb sebb: >>>>>> >>>>>> On 4 October 2015 at 15:48, Felix Schumacher >>>>>> <[email protected]> wrote: >>>>>>> >>>>>>> Hi all, >>>>>>> >>>>>>> I have spend a lot of time lately going through the docs for jmeter >>>>>>> and >>>>>>> especially looking at the markup side of the documentation. >>>>>> >>>>>> For which many thanks. >>>>>> >>>>>>> I have noticed a few things, that could be (hopefully) improved. >>>>>>> >>>>>>> Code examples >>>>>>> --------------------- >>>>>>> The code examples are all treated as plain text. There is no further >>>>>>> markup >>>>>>> to differentiate a shell script from an xml fragment or a java source >>>>>>> code >>>>>>> example. >>>>>>> >>>>>>> Maybe we could use a javascript library like >>>>>>> https://github.com/google/code-prettify? We would have to add an >>>>>>> language >>>>>>> attribute to each of our source code examples and extend the style >>>>>>> sheets. >>>>>> >>>>>> OK, so long as the JS library has a compatible license. >>>>>> >>>>>>> Layout of Menu-paths and key combos >>>>>>> --------------------------------------------------- >>>>>>> Paths through menu like structures and combination of keys are text >>>>>>> only. >>>>>>> I >>>>>>> propose to add markup (like in docbook) for this. >>>>>> >>>>>> Not sure I know what that means. >>>>> >>>>> You can see an example at >>>>> >>>>> http://people.apache.org/~fschumacher/jmeter/usermanual/doc-writers.html >>>> >>>> I see. >>> >>> Do you think we should include such markup? >>>> >>>> >>>>> And by the way, do you think such a page would be useful? And if so, >>>>> where >>>>> should it be located? >>>> >>>> We should document the tags that are being used. >>>> It's a developer resource, and doesn't belong in the user manual. >>>> We probably need to expand the online website to include more >>>> developer-centric materials. >>> >>> Any preference on the location? (Documentation, Community?) >>> >>>>>>> Notes >>>>>>> -------- >>>>>>> Notes can be used for different use cases like warnings or infos. I >>>>>>> think >>>>>>> it >>>>>>> would be nice to have an attribute on those notes to make them >>>>>>> distinguishable. The style of the note could reflect that attribute. >>>>>> >>>>>> OK >>>>>> >>>>>>> Icons with fonts >>>>>>> --------------------- >>>>>>> Fonts like https://fortawesome.github.io/Font-Awesome/ provide nice >>>>>>> looking >>>>>>> symbols, that scale well. Should we include such a font and use the >>>>>>> symbols >>>>>>> for notes, bugs, ...? Would it be a problem, if the font had a non >>>>>>> apache >>>>>>> license? >>>>>> >>>>>> Potentially, yes it might be a problem. >>>>>> Raise a LEGAL JIRA with specific proposals. >>>>> >>>>> Will try to. >>>>> >>>>>>> PDF files >>>>>>> ----------- >>>>>>> There are a few pdf files linked on the web page. Should we convert >>>>>>> them >>>>>>> to >>>>>>> xml? I don't think we would really loose anything. On the other hand >>>>>>> the >>>>>>> xml->html files would be better searchable by search sites. We could >>>>>>> link >>>>>>> to the original pdf files, if we want to keep them. >>>>>> >>>>>> There should be editable sources for the PDF files, e.g. in ODF >>>>>> format. >>>>>> No need to convert to XML (which would likely be much harder to >>>>>> maintain). >>>>> >>>>> It is not the editable source I am after. I think it is nicer to read >>>>> on >>>>> browsers, that have no pdf reader embedded. >>>> >>>> I see. >>>> >>>>> The documents seem to be pretty standard layout, so they should not >>>>> loose >>>>> anything when converted to standard doc html. The maintainance is a >>>>> point, >>>>> but a minor one in my eyes. >>>> >>>> Will they still be printable? >>>> They need to be usable off-line as well. >>> >>> Have you tried to look at the print layout of the current trunk docs? >>> With >>> the last changes they are at least as good as the printable version (at >>> least in my eyes and when printed with a modern browser :). >>>> >>>> >>>>>>> Usage of the different style sheets >>>>>>> ---------------------------------------------- >>>>>>> The web page and the "printable" pages are generated by different >>>>>>> style >>>>>>> sheets. As far as I can see, the "printable" pages are used by >>>>>>> jmeter's >>>>>>> internal doc system. Is there any other usage for those pages? >>>>>> >>>>>> Yes, they are used for off-line documentation. >>>>>> We should not expect users to have to go online for the documentation. >>>>> >>>>> I always looked at the documentation in the docs folder. >>>> >>>> The standard binary dist only only includes the printable-docs folder. >>>> (There are a few files under docs, but no html except under docs/api). >>>> >>>> I expect you are looking at your development workspace. >>> >>> You are right. >>> >>>>> If the printable >>>>> one is the preferred one, we should look at the colors at least. >>>> >>>> Fine to tweak the colours. >>>> >>>> But it would be wrong to use the website for offline browsing; the two >>>> serve different purposes. >>> >>> I would like to get the stylesheets to get closer for those two versions. >>> Therefore I would like to get to a table less version, or even use the >>> same >>> stylesheets with a parameterized run. >>> >>>>>>> If not, we could strip the number of generated "printable" files >>>>>>> further, >>>>>>> since I haven't seen a way to show any page except the >>>>>>> usermanual/component_reference and usermanual/functions pages. >>>>>> >>>>>> We need to keep offline docs. >>>>> >>>>> That's right. I think offline docs are really useful. >>>> >>>> Which is what the printable-docs are intended for. >>>> >>>>>>> The web pages should be printable with the latest additions in trunk >>>>>>> (at >>>>>>> least on firefox and chrome). >>>>>> >>>>>> The website pages have menus that are not useful for offline browsing. >>>>> >>>>> For me the question is, do they hurt so much, that we have to maintain >>>>> two >>>>> versions of the docs? >>> >>> And besides, the menu is not printed with the current version. Also, I >>> missed the menu while browsing the offline version. >>> >>> Regards, >>> Felix >>> >>>>> >>>>> Regards, >>>>> Felix >>>>> >>>>>>> What do you think? >>>>>>> >>>>>>> Regards, >>>>>>> Felix >>>>>>> >>>>>>> >>>>>>> >
