On 5 October 2015 at 21:12, Felix Schumacher <felix.schumac...@internetallee.de> wrote: > Am 05.10.2015 um 17:18 schrieb sebb: >> >> On 4 October 2015 at 15:48, Felix Schumacher >> <felix.schumac...@internetallee.de> 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. > 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. >> >>> 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. >> >>> 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. > 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. >> >>> 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? > > > Regards, > Felix > >> >>> What do you think? >>> >>> Regards, >>> Felix >>> >>> >>> >
