View Issue Details

IDProjectCategoryView StatusLast Update
0016610mantisbtdocumentationpublic2014-12-08 00:33
ReporterHorinius Assigned Todregad  
PrioritynormalSeverityfeatureReproducibilityhave not tried
Status closedResolutionfixed 
Target Version1.3.0-beta.1Fixed in Version1.3.0-beta.1 
Summary0016610: Suggestion for Admin Guide: Vars' default values on new line
Description

For the administrator guide document, I have a little suggestion here which could improve the doc quality even more. My suggestion is to write variables' default values on a new line/paragraph. The idea is to make it easier to spot these default values, so one can see if he needs to change the variable value or not.

Take $g_file_upload_method as an example. Currently, it’s written like this where the default value is buried inside the whole paragrph:

$g_file_upload_method

Specify the location for uploading attachments. This can be DISK, DATABASE,
or FTP. In case of FTP, the files are saved on the webserver (same as disk)
as well as on the specified FTP server. Default value is DATABASE. In case
of DISK / FTP upload methods you need to provide the webserver with write
access rights to the configured upload path (configured in the project)
and temporary upload path (used by PHP).

What I suggest is something like this (the Values line is optional):

$g_file_upload_method

Values: DISK, DATABASE, FTP

Specify the location for uploading attachments. In case of FTP, the files
are saved on the webserver (same as disk) as well as on the specified FTP
server. In case of DISK / FTP upload methods you need to provide the
webserver with write access rights to the configured upload path
(configured in the project) and temporary upload path (used by PHP).

Default: DATABASE
TagsNo tags attached.

Relationships

related to 0017781 closeddregad Suggestion: breaking Configuration.xml file into smaller pieces 

Activities

dregad

dregad

2013-11-14 06:03

developer   ~0038550

Thanks for your suggestion for improvement.

Our documentation is stored in XML files [1]. If you want to see these changes any time soon, I invite you to submit a pull request with your improvements :)

[1] https://github.com/mantisbt/mantisbt/tree/master/docbook/Admin_Guide/en-US

Horinius

Horinius

2013-11-17 12:10

reporter   ~0038572

A pull request has been submitted with a GitHub user called cheesecracker.
Please check if that's what you meant.

dregad

dregad

2013-11-17 15:58

developer   ~0038574

Yes, that's the idea. I added some comments in your pull request [1]

[1] https://github.com/mantisbt/mantisbt/pull/97

Horinius

Horinius

2013-11-18 07:02

reporter   ~0038579

I've seen that you've taken the changes. Yeah, just do whatever you like :)
I'm going to remove the branch and/or the forked repo.

For the other similar configs in the admin doc, I'll leave to for you :)

Bye

dregad

dregad

2013-11-18 09:03

developer   ~0038582

I've seen that you've taken the changes

I'm not sure what you mean by that. I have done nothing except comment on your pull request, and it was you (or cheesecracker if that's another person), not me, who closed it.

With regards to the other configs, I have other and more urgent things to do to than to change them - as mentioned before, if you want this change I suggest you take the time to submit them yourself otherwise it is not going to happen.

Horinius

Horinius

2013-11-18 09:35

reporter   ~0038583

Ah! I received all those comments, esp the message
"I reworded the commit message - note, prefixing issue number with # allows automatic pick up by our source control integration"
so I thought it's already included in the main trunk and that's why I closed it ^_^

OK, I'll open it again. I'm not used to Git. So do tell me when it's done.

Horinius

Horinius

2013-11-19 11:24

reporter   ~0038594

FYI, I deleted that branch and created another branch.

dregad

dregad

2013-11-19 14:07

developer   ~0038596

The new pull request was not really necessary.

Anyway, I've merged the change in; feel free to submit additional changes for other config items.

dregad

dregad

2013-12-03 05:31

developer   ~0038817

Resolving the issue since Horinius is apparently not going to submit further updates to the documentation.

Horinius

Horinius

2014-10-09 13:02

reporter   ~0041489

I have had many things to do in real life and my job. That's why I didn't submit anything further.

About the other branch: I was still in my learning curve in this GitHub, so I was a bit lost. I created another branch to make sure I didn't screw up things :)

Is it possible to break the file Configuration.xml into smaller files -- one for each chapter? The file has thousands of line and it always took me a while to get to the place I wanted to change. Anyway, it's always better to have smaller files because that would reduce the chance two people changing the same file at the same time.

Actually, I saw that "admin guide" itself is already divided into small files, so that must be possible, right?

Few days ago, I tried to compile the guide with Publican by following the README but failed. I used XP. Are you using Linux?

Related Changesets

MantisBT: master 229a67df

2013-11-18 05:50

cheesecracker

Committer: dregad


Details Diff
Documentation: making default value more obvious

$g_file_upload_method as an example.

Issue 0016610
Affected Issues
0016610
mod - docbook/Admin_Guide/en-US/Configuration.xml Diff File